Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the planning-and-task-breakdown skill?
The planning-and-task-breakdown skill makes Claude Code and other coding agents turn a spec into a written plan of small, ordered tasks, each with acceptance criteria, a way to verify it, and checkpoints between phases, before any code is written. It is for developers who hand agents multi-step work and want it done in pieces they can check.
It comes from addyosmani/agent-skills, Addy Osmani's MIT-licensed set of 25 engineering skills, where it is the PLAN step between the spec-driven development skill and the build. The skill's description reads: "Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible."
It is the sixth most installed skill in the repo. As of 24 October 2026, its skills.sh page listed 63.0K installs (snapshot, 24 October 2026), with Pass results from all three security audits shown (Gen Agent Trust Hub, Socket and Snyk).
What does it do?
The SKILL.md describes a five-step process:
- Plan in read-only mode. Read the spec and relevant code, note existing patterns, map dependencies and list risks. "Do NOT write code during planning."
- Map the dependency graph. For example schema, then API types, then endpoints, then the frontend client, then UI. Build order follows the graph from the bottom up.
- Slice vertically. Instead of "build entire database schema" then "build all API endpoints", each task is one complete path, such as "User can create an account (schema + API + UI for registration)." Every slice delivers something testable.
- Write tasks. Each one has a description, acceptance criteria, verification (tests, build, a manual check), dependencies, files likely touched, and an estimated scope.
- Order and checkpoint. Satisfy dependencies first, leave the system working after every task, put high-risk tasks early, and add a checkpoint every two or three tasks where tests pass, the app builds, and a human reviews before going on.
Task sizing comes from a table:
| Size | Files | Example from the skill |
|---|---|---|
| XS | 1 | Add a validation rule |
| S | 1 to 2 | Add a new API endpoint |
| M | 3 to 5 | User registration flow |
| L | 5 to 8 | Search with filtering and pagination |
| XL | 8+ | Too large, break it down further |
"An agent performs best on S and M tasks." The skill adds four signs a task needs splitting: it would take more than one focused session (roughly two hours of agent work), it needs more than three acceptance criteria, it touches two independent subsystems, or its title contains "and."
Output files. The plan goes to tasks/plan.md (overview, architecture decisions, phased task list with checkpoints, risks, open questions) and the tasks to tasks/todo.md. If your project's CLAUDE.md or AGENTS.md, or you, name an issue tracker such as GitHub Issues, Jira, Linear or beads, the agent creates one tracker item per task instead, and the plan lists their IDs.
One safety rule stands out: "Never overwrite an incomplete plan." If tasks/plan.md or tasks/todo.md already has unchecked tasks for different work, the agent must stop and ask, since another session may be mid-build.
It also covers parallel work: independent slices, tests and docs can run in parallel; migrations and shared state must be sequential; features sharing an API contract need the contract defined first.
What's in the folder: only SKILL.md. Its "See Also" section links to references/definition-of-done.md at the repo root, a standing checklist every task must clear on top of its own acceptance criteria. That file is outside the skill folder.
How do you install the planning and task breakdown skill?
Whole set as a Claude Code plugin. From the README:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
This adds every skill, the shared checklists and nine slash commands, including /plan. Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so the skill is /agent-skills:planning-and-task-breakdown. If the marketplace step fails over SSH, the README gives an HTTPS form: /plugin marketplace add https://github.com/addyosmani/agent-skills.git.
Just this skill. The command on skills.sh, using the skills CLI:
npx skills add https://github.com/addyosmani/agent-skills --skill planning-and-task-breakdown
Add -g for all projects. The folder lands in .claude/skills/planning-and-task-breakdown/, or ~/.claude/skills/planning-and-task-breakdown/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
The README warns that a per-skill install "copies only skills/<name>/, not the repo-level references/ directory. The skill still works, but paths to supplementary shared checklists are unavailable." Here that is definition-of-done.md. Use the plugin, or copy that file into a references/ folder inside the installed skill.
How do you use it?
With the plugin, run /plan after you have a spec. Its command file tells the agent to read SPEC.md (or an equivalent) and the relevant code, work read-only, slice vertically, add checkpoints, present the plan for your review, and save it to tasks/plan.md and tasks/todo.md. Claude Code also has a built-in /plan command that enters plan mode, listed in its commands reference and described in the plan mode docs as a prefix for a single prompt. If typing /plan gives you the built-in behavior, use the namespaced form /agent-skills:plan, which the README recommends whenever a plugin command shares a built-in's name.
Example prompts (suggestions, not quotes from the repo):
/plan(with an approvedSPEC.mdin the repo root)Use the planning-and-task-breakdown skill to split the CSV import spec into tasks. Track them as GitHub Issues.This ticket feels too big to start. Break it into S and M tasks with acceptance criteria.Plan the search feature so two agents can work in parallel. Define the API contract first.
After approval, the repo's /build command implements the next pending task test-first and stops; /build auto runs every task after one approval of the plan.
Requirements: none beyond a repo the agent can write to, and your tracker's CLI or integration if you want tasks outside tasks/todo.md. There are no scripts or API keys.
How does it compare with plan mode and Superpowers?
addyosmani planning-and-task-breakdown |
Superpowers writing-plans | Claude Code plan mode | |
|---|---|---|---|
| What it is | A skill about plan content and files | A skill about plan content and files | A built-in permission mode |
| Task unit | Vertical slice, sized XS to XL by files touched | Smallest unit with its own test cycle | Not defined |
| Output | tasks/plan.md, tasks/todo.md or tracker items |
A plan file with a fixed header and steps | A plan you approve in the session |
| Editing during planning | Not allowed by the skill | Runs before code is touched | Blocked until you approve, per the docs |
Plan mode controls what Claude is allowed to do; the two skills shape what the plan says. You can combine this skill with plan mode: plan read-only, approve, then build.
Tips and limits
From the files, not from testing:
- It writes into
tasks/. Decide whether those files belong in git. The skill and the/buildcommand expect them there by default. - It refuses to overwrite. An old plan with unchecked tasks makes it stop and ask. Finish, discard or move the old plan to proceed.
- File counts are a proxy. Sizing by files touched works for typical app code; a one-file change can still be large. Use the "and in the title" and acceptance criteria tests too.
- Human checkpoints are built in. Checkpoints include "Review with human before proceeding." If you want fewer stops,
/build autokeeps a single approval. - No scripts. It runs nothing on its own.
- License. MIT, so you can fork it and change the templates as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md; for a repo with many skills it shows a list to pick from, so you can take spec-driven-development alongside it. You can also drop a folder or a .zip, which lets you add definition-of-done.md to the skill's references/ folder first. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.
Similar skills
- Spec-driven development skill: the step before, writing the spec this skill breaks down.
- Writing plans skill: Superpowers' spec-to-plan skill with interfaces and test steps per task.
- Executing plans skill: Superpowers' skill for running a written plan.
- Claude Code plan mode: the built-in read-only mode for planning.