The Problem: When Your AI Agent Gets Lost in the Weeds
You've given your AI agent a clear spec. You've described the feature you want built. You've even provided context about the existing codebase. Yet, after a few minutes of work, the agent produces a tangled mess—half-finished functions, missing error handling, and tests that don't cover the actual requirements.
This isn't a rare occurrence. It's a common failure mode when agents tackle complex tasks without a structured approach. The core issue is that large, ambiguous tasks overwhelm an agent's ability to plan and execute coherently. The agent might start implementing one part, realize it needs another piece, backtrack, and end up with a jumbled implementation that's hard to verify.
Why This Happens
AI agents, especially those operating in code generation contexts, have finite context windows and reasoning capacity. When faced with a large task, they often:
- Jump into implementation too early without fully understanding dependencies
- Miss edge cases because the task scope is too broad to consider all scenarios
- Create inconsistent code as they switch between different parts of the problem
- Produce untestable output because acceptance criteria aren't explicitly defined
The result is wasted time, debugging headaches, and a loss of trust in the agent's capabilities. You end up spending more time fixing the agent's work than you would have spent doing it yourself.
What a Good Solution Should Change
An effective approach needs to transform vague requirements into concrete, ordered steps. It should:
- Force explicit planning before coding—no implementation until the path is clear
- Break work into small, verifiable chunks that can be completed in a single focused session
- Make dependencies explicit so the agent builds foundations first
- Include verification steps for each task to catch errors early
- Allow for parallelization when multiple agents or sessions are available
This isn't about making the agent "smarter"—it's about giving it a structured framework that compensates for its limitations.
Introducing the Planning and Task Breakdown Skill
One practical solution to this problem is the planning-and-task-breakdown skill. This skill provides a structured methodology for decomposing complex work into manageable tasks with clear acceptance criteria.
The skill isn't a magic solution—it's a disciplined approach that forces both the agent and the human to think through the work before starting. It's particularly useful when:
- You have a spec or clear requirements but need to break them into implementable units
- A task feels too large or vague to start
- Work needs to be parallelized across multiple agents or sessions
- You need to communicate scope to a human
- The implementation order isn't obvious
When This Skill Doesn't Apply
This skill isn't necessary for every situation. You might not need it when:
- Making single-file changes with obvious scope
- The spec already contains well-defined, ordered tasks
- The change is trivial (like fixing a typo or updating a constant)
Using it for simple tasks would add unnecessary overhead.
How the Skill Works in Practice
The skill follows a five-step process that transforms requirements into executable plans.
Step 1: Enter Plan Mode (Read-Only Analysis)
Before writing any code, the agent operates in read-only mode. It reads the spec and relevant codebase sections, identifies existing patterns and conventions, maps dependencies between components, and notes risks and unknowns.
Critical rule: No code is written during this phase. The output is a plan document, not implementation.
Step 2: Identify the Dependency Graph
The agent maps what depends on what. For example:
Database schema
│
├── API models/types
│ │
│ ├── API endpoints
│ │ │
│ │ └── Frontend API client
│ │ │
│ │ └── UI components
│ │
│ └── Validation logic
│
└── Seed data / migrations
Implementation order follows this graph bottom-up: build foundations first.
Step 3: Slice Vertically, Not Horizontally
This is where many developers (and agents) go wrong. Instead of building all the database, then all the API, then all the UI, the skill enforces vertical slicing—building one complete feature path at a time.
Bad (horizontal slicing):
Task 1: Build entire database schema
Task 2: Build all API endpoints
Task 3: Build all UI components
Task 4: Connect everything
Good (vertical slicing):
Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a task (task schema + API + UI for creation)
Task 4: User can view task list (query + API + UI for list view)
Each vertical slice delivers working, testable functionality.
Step 4: Write Structured Tasks
Each task follows a specific template:
## Task [N]: [Short descriptive title]
**Description:** One paragraph explaining what this task accomplishes.
**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]
**Verification:**
- [ ] Tests pass: `npm test -- --grep "feature-name"`
- [ ] Build succeeds: `npm run build`
- [ ] Manual check: [description of what to verify]
**Dependencies:** [Task numbers this depends on, or "None"]
**Files likely touched:**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`
**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]
Step 5: Order and Add Checkpoints
Tasks are arranged so dependencies are satisfied, each task leaves the system in a working state, and verification checkpoints occur after every 2-3 tasks. High-risk tasks are placed early to fail fast.
Explicit checkpoints look like this:
## Checkpoint: After Tasks 1-3
- [ ] All tests pass
- [ ] Application builds without errors
- [ ] Core user flow works end-to-end
- [ ] Review with human before proceeding
Practical Considerations
Task Sizing Guidelines
The skill provides clear sizing guidelines:
| Size | Files | Scope | Example |
|---|---|---|---|
| XS | 1 | Single function or config change | Add a validation rule |
| S | 1-2 | One component or endpoint | Add a new API endpoint |
| M | 3-5 | One feature slice | User registration flow |
| L | 5-8 | Multi-component feature | Search with filtering and pagination |
| XL | 8+ | Too large — break it down further | — |
If a task is L or larger, it should be broken into smaller tasks. Agents perform best on S and M tasks.
When to break a task down further:
- It would take more than one focused session (roughly 2+ hours of agent work)
- You cannot describe the acceptance criteria in 3 or fewer bullet points
- It touches two or more independent subsystems (e.g., auth and billing)
- You find yourself writing "and" in the task title (a sign it is two tasks)
Parallelization Opportunities
When multiple agents or sessions are available:
- Safe to parallelize: Independent feature slices, tests for already-implemented features, documentation
- Must be sequential: Database migrations, shared state changes, dependency chains
- Needs coordination: Features that share an API contract (define the contract first, then parallelize)
Output Files
The skill produces two key files:
- Plan document: Saved to
tasks/plan.md - Task list: Saved to
tasks/todo.md
These paths are conventions expected by downstream tooling.
Evaluating Whether This Skill Fits Your Workflow
Best Use Cases
This skill shines when:
- Building new features that span multiple files or components
- Refactoring existing code where dependencies need careful mapping
- Onboarding to unfamiliar codebases where the agent needs to understand structure before changing it
- Coordinating multiple agents working on related tasks
- Estimating project scope for human review before implementation
When to Avoid It
Don't use this skill when:
- The change is trivial and well-understood
- You're making a single-file edit with obvious scope
- The spec already contains perfectly ordered, sized tasks
- Time pressure makes planning overhead unacceptable (though this is usually a false economy)
Setup Context
The skill is part of the agent-skills repository by Addy Osmani. It's designed to work with AI coding agents that can follow structured instructions. No special installation is required beyond having the skill available in your agent's skill directory.
Safety Signals
- The skill emphasizes read-only planning before implementation
- It requires explicit acceptance criteria for every task
- It includes verification steps to catch errors early
- It promotes small, focused tasks that are easier to review and test
Repository Signals
The agent-skills repository has significant community traction with over 76,000 stars. The skill is part of a curated collection designed to improve agent reliability. The repository includes documentation and examples, though as with any open-source tool, you should review the implementation to ensure it fits your security requirements.
Common Pitfalls and How to Avoid Them
"I'll figure it out as I go"
This is how you end up with tangled implementations and rework. Ten minutes of planning saves hours of debugging.
"The tasks are obvious"
Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases.
"Planning is overhead"
Planning is the task. Implementation without a plan is just typing.
"I can hold it all in my head"
Context windows are finite. Written plans survive session boundaries and context compaction.
Red Flags to Watch For
If you see these patterns, the planning process needs improvement:
- Starting implementation without a written task list
- Tasks that say "implement the feature" without acceptance criteria
- No verification steps in the plan
- All tasks are XL-sized
- No checkpoints between tasks
- Dependency order isn't considered
Getting Started
If you're dealing with complex tasks that your AI agent struggles to complete reliably, consider inspecting the planning-and-task-breakdown skill. Start with a small, well-defined project to see how the structured approach affects your agent's output quality.
The skill won't make your agent smarter, but it will give it a framework that compensates for its limitations—turning vague requirements into concrete, verifiable steps that lead to more reliable results.