How to use the Subagent-Driven Development agent skill

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder with a SKILL.md file that gives an AI agent a set of instructions for a particular kind of task. This skill, from the obra/superpowers collection, is licensed under MIT and is described as: use when executing implementation plans with independent tasks in the current session.

Once active, the agent follows a fixed process. It dispatches a fresh implementer subagent for each task with only the context that task needs, then runs a task review that checks spec compliance and code quality. A broader review of the whole branch runs at the end. The agent records its progress in a ledger file so it can resume after its memory is compacted.

Install the skill (ZIP download or Claude apps upload)

Download the skill as a ZIP from our page and unzip it. To use it for all your projects, place the unzipped folder in ~/.claude/skills/. To use it for a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your repository
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you start

The skill is built around executing plans inside a git repository. It needs a git repository with worktree support, an agent runtime that can dispatch subagents, and Bash so the agent can run the scripts/sdd-workspace helper. The workflow also refers to companion skills: using-git-worktrees, finishing-a-development-branch and executing-plans. The sdd-workspace script itself is not among the listed files, so confirm it is present in the skill folder before relying on it.

If your environment has no subagent tool, the skill directs the agent to the inline executing-plans skill instead.

• Git repository with worktree support
• A subagent-capable agent runtime
• Companion skills: using-git-worktrees, finishing-a-development-branch, executing-plans
• Bash, to run scripts/sdd-workspace PLAN_FILE

Trigger the skill with a natural request

You do not need special syntax. Give the agent a written plan file and ask it to execute the plan. The skill's description tells the agent to use it when it is executing an implementation plan whose tasks are independent, in the current session.

Be specific about the plan file and the fact that you want it run hands-off. The skill will then set up a workspace, read the plan once and create a todo per task. The skill tells the agent not to pause between tasks to ask whether it should continue.

• "Execute docs/plans/payments-refactor.md using subagent-driven development."
• "Work through this implementation plan task by task and review each one, without stopping for check-ins."
• "Resume the plan in docs/plans/import-pipeline.md from where the ledger left off."

What happens during a run

The agent first sets up an isolated workspace using git worktrees and creates a git-ignored workspace for the plan under .superpowers/sdd/. It keeps a ledger file named progress.md there, whose first line identifies the plan. For each task, the implementer implements, tests, commits and self-reviews, then a task reviewer checks the diff. If the review finds problems, the agent runs a fix loop before marking the task complete.

The skill says the agent stops only in four cases: an irreversible or destructive operation, a security-sensitive action, a side effect outside the worktree that norms say to ask about first (such as a merge, a push to a shared branch or a publish), and a plan so broken that every path forward is a guess. Other decisions are recorded in the ledger as rulings and the run continues.

• Ledger line format for decisions: Ruling: <what you decided> — <why> — <what it costs if wrong>
• If context is compacted, the agent trusts the ledger and git log over its own memory
• Running git clean -fdx will destroy the workspace, so avoid it mid-run

Safety notes: scripts and network use

The skill runs scripts: it calls the scripts/sdd-workspace helper through Bash to create the plan's workspace directory. It does not use the network, according to its listing. Because the agent is told to proceed without asking, review the ledger and the commits on the worktree branch before you merge or push anything.

Destructive operations, pushes and publishes are among the stop conditions, but you should still check the diff yourself. Avoid running the skill against a main or master branch without your explicit consent, since the skill itself says implementation should not start there without it.

• Scripts: yes (scripts/sdd-workspace)
• Network: no
• Review the ledger and commits before merging

Tips for better results

Write a plan whose tasks are mostly independent. The skill is a poor fit for tightly coupled work, where the skill itself recommends brainstorming or executing manually. Attach a spec if you have one, because the skill reads it as the authority when the plan conflicts with it. Without a reachable spec, the agent notes that in the ledger and treats its rulings as provisional.

For many small, identical edits, ask for them to be grouped: the batching reference describes sending one subagent a single brief listing every file, rather than one dispatch per task.

• Keep tasks independent and clearly described in the plan
• Provide a spec file if the plan depends on one
• Use a git repository and keep the workspace out of version control (it is git-ignored)