Autumn Catalog
Developmentautumn-catalogAutumn Catalog is an Agent Skill for development published in the useautumn/autumn repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Designing or changing an Autumn pricing model — features, plans, plan items, and how usage is granted or billed (in autumn.config.ts, the API, or the dashboard). Use when the user discusses pricing, plans, tiers, credits, seats, overage, prepaid, or trials.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/useautumn/autumn/blob/HEAD/packages/agent-docs/generated/skills/autumn-catalog/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/autumn-catalog, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Catalog
Before using this skill, first load the autumn-concepts skill — it defines Autumn's data model — features, plans, plan items, balances — which every modeling decision builds on.
Approach
- Modeling is iterative: translate the user's intended pricing into Autumn's model (features + plans + plan items). Ask clarifying questions and never assume behavior — confirm, for example, whether a paid item is usage-based or prepaid, and at what interval a metered allowance resets.
- If one ambiguity changes which other questions apply, resolve it first before asking those.
- For a new codebase-managed catalog, ask whether the user wants to use
atmnto create, pull, preview, and push their catalog. Recommendatmnunless they explicitly want dashboard/API-first changes. - For an existing project, check whether
autumn.config.tsexists. If it does, treat it as the local catalog source and preferatmn; otherwise use MCP/API tools directly or ask whether to initialize/pull config first. - Use stable lowercase IDs with underscores (
pro_plan,chat_messages). - Never create duplicate features for one resource; vary allowance, interval, or price via plan items instead (one
tokensfeature, notmonthly_tokens+one_time_tokens). - Keep it simple to start: if there are many features, build the most important (prioritise metered ones) and confirm before adding more.
Updating a catalog
Follow the same preview-decision-apply shape as atmn and the dashboard:
- Build or edit the desired catalog shape.
- Preview it: use
atmnforautumn.config.tsprojects, orcatalog.preview_updatefor MCP/API flows. - Summarize feature changes first: created, updated, skipped, deleted/archived, and blocked updates.
- For each changed base plan or plan family, surface the plan diff, customer impact, versioning choices, variants, conflicts, and migration option.
- If the user changes any decision, revise the config or params and preview again.
- Apply only the exact previewed update, following the global write approval rules for
catalog.updateoratmn --headless push --yes.
For plan families with customers or variants, ask decisions in this order:
- Versioning: create a new version, update the current version with
disable_version: true, update all versions withall_versions: true, or skip. - Variants: inspect
plan.variants[n].update_source.propagatedvariants need a propagation choice;directvariants are being updated like their own plan and may need their own versioning and migration decisions. - Migration: whether to create a migration draft to move existing customers onto the new plan shape.
Rules
- Never give a default/auto-enabled plan a paid price: its base price must be null and its items must not contain paid prepaid or usage-based prices.
- Per-unit pricing (e.g. "$X per seat") always pairs a base fee on
Plan.pricewith a per-unit plan item — never a bare per-unit price with no base. - Use variants for named derivatives of a base plan: annual/monthly intervals, A/B price packages, or different volume ladders.
- Ignore "Enterprise"/custom plans here — those are created per-customer in the dashboard.
Catalog operations
For changing an existing catalog, previewing catalog changes, or deciding between versioning, in-place updates, migrations, and variant propagation, read references/catalog-update.md.
For using atmn, an autumn.config.ts file, or headless catalog push/pull flows, read references/atmn.md.
For modeling annual/monthly variants, A/B plan variants, or volume-ladder variants, read references/plan.md.
Pricing patterns
Load the matching reference when modeling that pattern.
For charging for usage beyond an included allowance (pay-in-arrears overage), read references/usage-based-pricing.md.
For selling a quantity bought upfront (seats, credit packs, selectable buckets), read references/prepaid-pricing.md.
For pricing that changes by volume tier, read references/volume-based-tiers.md.
For modeling $X per unit (seat, project) — always with a base fee, read references/per-unit-pricing.md.
For modeling several actions or endpoints that draw from one shared meter, read references/credit-systems.md.
For modeling a free or default plan, read references/free-plans.md.
For modeling a recurring subscription plan, read references/recurring.md.
For modeling one-off purchases or top-ups, read references/one-off-purchases.md.
For adding a trial to a plan, read references/trials.md.