How to use the executing-plans agent skill: step by step

What the executing-plans skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent a set of instructions for one kind of task. This skill covers the case where you have a written implementation plan and the agent should do the work in its own session. It works through the plan's tasks in order, follows the test-first steps in the plan, and checks each step's expected output before moving on.

Progress is written to a ledger file, so the agent can pick up where it left off if the conversation's context is compressed. At the end it runs one review of the whole branch, ideally with a reviewer that starts with fresh context. It only stops to ask you about destructive actions, security matters, side effects outside the worktree such as merging or publishing, or a plan too broken to follow.

Install executing-plans with the ZIP file

Download the ZIP for the skill from this page and unzip it. The skill is a folder that contains SKILL.md. Put that folder in one of two places, depending on how you want to use it.

For all of your projects, place it in ~/.claude/skills/. To use it only inside one project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal use across projects: ~/.claude/skills/
• One project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The skill assumes a few things are already in place. It needs git, and a shell that can run Bash so the bundled scripts (sdd-workspace, task-start, task-done and review-package) can run. You also need a written implementation plan file, ideally with a linked spec, and a test command for each task.

The skill names several companion skills it relies on: test-driven-development, systematic-debugging, verification-before-completion, using-git-worktrees, requesting-code-review, finishing-a-development-branch and subagent-driven-development. Check that these are available in your setup before a long run.

• git
• A Bash-capable shell for the bundled scripts
• A written implementation plan file, ideally with a linked spec
• A test command for each task
• The companion skills listed above

Trigger the skill with a natural request

You do not need a special command. Tell the agent in plain language that you want the plan carried out inline in this session. The skill is meant for cases where you chose inline execution at handoff, or where the environment has no sub-agent tools.

Say which plan file to use and that you want it executed in this session. The skill also states that it should be used when the agent has a written plan from a planning step and the tasks are largely independent of each other.

• 'Execute the plan in docs/plans/payments.md inline in this session.'
• 'We chose inline execution. Work through every task in the plan file without stopping between tasks.'
• 'You have no sub-agent tools here, so run the implementation plan yourself and keep a progress ledger.'

How a run works, task by task

Before task 1, the agent creates an isolated worktree, sets up a per-plan workspace and ledger, reads the plan and its spec, and checks for conflicts between tasks. Each task starts with the task-start script, which prints the brief path and the BASE commit the task's range starts from. Steps run in order, each test is run to see it fail and then pass, and each command's output is compared with the plan's Expected line.

When a task is finished, the task-done script runs the test command you give it, saves the full output in the workspace, and writes a completion line to the ledger only if the tests pass. Choices the agent makes that differ from the plan are recorded as Ruling lines. After the last task, the agent runs review-package against the branch and reviews the result.

• Ledger file: <repo-root>/.superpowers/sdd/<plan filename>/progress.md
• Completion line format: Task <N>: complete (commits <base7>..<head7>, tests: <command> → <result>)
• Each judgement call is written as: Ruling: <what was decided> — <why> — <cost if wrong>

Example requests and what the agent does with them

A typical request names the plan and the mode. If a previous run was interrupted, ask the agent to resume from the ledger. The skill says that tasks already marked complete in the ledger should not be redone, and work should continue from the first task without a completion line.

If the plan file named in the ledger's first line is a different plan, the agent is told to leave that ledger alone and start its own.

• Start a new run: 'Carry out docs/plans/export.md inline. Use the ledger to track progress.'
• Resume after a crash or compaction: 'Continue the executing-plans run for docs/plans/export.md from the ledger.'
• Ask for a self-review: 'The final review should be your own, since we have no sub-agent tool here.'

Safety notes: scripts, git and deletion

This skill runs scripts, so read them before you trust a run. It is stated not to use the network. The skill's workspace is a git-ignored scratch area, and running git clean -fdx will destroy it. If that happens, the skill says to recover from git log.

At the end, once the final review is clean and its fixes are committed, the skill deletes the plan's workspace directory. If you do not want the agent to create worktrees, ledger files or run cleanup commands, do not use this skill in that repository. The skill also stops and asks you before any irreversible action, security matter, merge, push to a shared branch or publish.

• Runs scripts: yes
• Uses network: no
• The workspace is git-ignored; git clean -fdx destroys it
• The workspace directory is deleted at the end of a clean run