How to use the Compose Next agent skill

What the Compose Next skill makes the agent do

The skill is for multi-step feature work, bug fixes or refactors where requirements need to settle, where the feature should be documented, and where the change deserves independent review before merge.

When explicitly requested, the agent asks questions one decision at a time, sets up an isolated git worktree on a new branch, writes a single feature design document with tasks and acceptance criteria, then implements, verifies and reviews the work. The skill's stated phases are grill, workspace, spec, implement, verify, review, finalize and finish.

• Requirements are settled through one-question-at-a-time decisions.
• Changes go into a linked git worktree on a new branch, by default at .worktrees/{slug}.
• One feature document holds design, tasks and acceptance criteria, by default at docs/compose/spec/{feature-name}.md.
• Without an explicit request, the agent does the work directly and skips this process.

Install the compose-next skill

Download the compose-next ZIP from this page. Then choose one of the install routes below.

For a personal install, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with a natural request

The skill runs only when you explicitly ask for this workflow. You can type /compose-next, name the skill, or use any other clear natural-language request for the workflow. You do not need to know the skill's internal name.

The skill does not start just because a task is large. A one-shot edit, a single-file tweak or a plain question will not trigger it, and the skill says those need no orchestration overhead.

• /compose-next add CSV export to the reports page
• Use the compose-next workflow to fix the login redirect bug
• Run this refactor through the Compose workflow with a design doc

Example: a feature with a design document

After you ask for the workflow, the agent first inspects the repository, its instructions (such as AGENTS.md or README) and existing spec files. It then asks only the questions the environment cannot answer, one decision at a time, and does not start implementation until requirements and scope are settled.

When the design is ready, the spec file holds problem, design, out-of-scope items and a task list in which each task has an observable acceptance criterion. The Report section stays empty until the work is finalized.

• Settled decisions and contracts are recorded; exploration history is not.
• Tasks can declare depends: links, which must not form cycles.
• Small changes get a small document; the skill says not to pad designs.

Requirements and safety notes

The skill needs git with worktree support. It also needs the project's own dependency tooling, for example bun or uv, and it prefers lockfile-frozen install commands such as bun ci or uv sync --frozen. A question tool or interactive input is preferred but not required.

The skill does not run bundled scripts and does not use the network, according to its listing. It does write files and run git commands inside your project, so avoid it in repositories where you do not want the agent creating worktrees, docs/ folders or branches.

The skill will not begin implementation on main or master without your explicit consent. If you say without worktree or name a workspace path, it uses that choice.

• Requires: git with worktree support
• Requires: project dependency tooling as defined by the repository
• Runs scripts: no
• Uses network: no

Tips for getting good results

Give the agent a clear goal and say whether you want a spec. If you say without spec or this is a small fix, the skill skips the feature document and its spec gate, but keeps verification and review where the task warrants them.

If a project has its own worktree path, branch convention or spec path in AGENTS.md or user configuration, the skill uses that instead of the defaults and records the override.

• State the workflow explicitly so it is not triggered by accident.
• Answer the single decision questions the agent asks; unrelated decisions come in separate turns.
• Review the spec before implementation if you are available to approve it.