How to use the Planning and Task Breakdown agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. The agent loads the skill when a request matches the skill's description, so you do not have to paste the instructions into every chat.

This skill is defined in a single file, SKILL.md, in the skills/planning-and-task-breakdown folder of the addyosmani/agent-skills repository. It is licensed under MIT.

What the skill makes the agent do

When the skill is active, the agent works in a read-only planning mode first. It reads the spec and the relevant parts of the codebase, identifies existing patterns, maps which components depend on which, and notes risks and unknowns. It does not write code during planning.

The output is a plan saved to tasks/plan.md and a task list. Each task includes a description, acceptance criteria, verification steps, dependencies, files likely touched and an estimated scope (XS, S, M, L or XL). The skill favours vertical slices, where each task delivers one working feature path, and adds checkpoints after every two or three tasks.

• Reads the spec and code without modifying it
• Maps dependencies and orders tasks so foundations come first
• Splits work into tasks sized from XS to L, and breaks XL work down further
• Records the task list in tasks/todo.md by default, or in an external tracker if the project specifies one

How to install the skill

There are two ways to install it. Download the ZIP for this skill from this page and then either unzip it into your personal skills folder or into a project's skills folder.

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

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

The skill's description tells the agent to use it when you have a spec or clear requirements and need implementable tasks, when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. You can phrase requests in those terms.

Give the agent the spec or requirements along with the request. The more concrete the spec, the more useful the resulting task list.

• Here is the spec for the notifications feature. Break it into implementable tasks before writing any code.
• This task feels too big to start. Plan it into small steps and estimate the scope.
• Split this spec so two agents can work on it in parallel.
• Plan the checkout rewrite as tasks with acceptance criteria and checkpoints.

What to expect from the output

Expect a plan document first, then a task list. Review the dependency order and checkpoints before you tell the agent to implement anything. Tasks estimated as L or XL should be broken down further according to the skill's rules.

If the project already has a plan file with unchecked tasks, the skill tells the agent to stop and ask you rather than overwrite it. This can pause the session until you decide how to proceed.

• Check that each task has testable acceptance criteria
• Confirm the dependency order matches your codebase
• Look for checkpoints after every two or three tasks

Safety notes: scripts and network

The skill's listing states that it runs no scripts and uses no network access. It requires nothing else to be listed. The skill itself only writes planning files, such as tasks/plan.md and tasks/todo.md, and it tells the agent not to write implementation code during planning.

Because the agent is told not to overwrite existing plans, check that any file it creates is where you expect before continuing.

• Runs scripts: no
• Uses network: no
• Writes planning markdown files; creates the tasks/ directory if it is missing

Tips for better results

The skill works best when the spec is clear. If you are unsure, ask the agent to list open questions in the plan's Open Questions section before it breaks the work down.

If your team tracks work in an issue tracker, name it in your project's agent rules such as CLAUDE.md or AGENTS.md, or say so in the request. The skill then creates one tracker item per task instead of tasks/todo.md.

• Give the full spec, not a summary
• Name your issue tracker if you use one
• Review the plan before implementation starts
• Use it for multi-file work, not one-line fixes