Task Planning Skill

An agent skill that turns a product/technical objective into a structured, executable task plan: JSON files per epic, explicit dependencies, priorities, statuses, and file-level create/modify targets.

Works with Claude Code, Cursor / agent skills, and Devin via the shared skill layout in this repository.

Author: Bogdan Nistor · bnistor.dev

What it does

When you ask for an implementation plan, development plan, or technical roadmap, the agent:

1. Creates a dedicated folder for the objective (or tasks/ for whole-project plans)
2. Writes an index.json catalog plus numbered epic JSON files (00-…, 01-…, …)
3. Fills each task with actionable steps, acceptance criteria, dependencies, and explicit filesToCreate / filesToModify
4. Validates all JSON and reports epic/task counts plus the first runnable task

Repository layout

.
├── README.md
├── .agents/skills/task-planning/SKILL.md   # Cursor / Grok-style agents
├── .claude/skills/task-planning/SKILL.md   # Claude Code
└── .devin/skills/task-planning/SKILL.md    # Devin

The three SKILL.md files are identical in content so you can drop the whole repo into a project or copy only the path your tool expects.

Install

Claude Code

Copy the skill into your project or personal skills directory:

# Project-level
mkdir -p .claude/skills
cp -r path/to/this-repo/.claude/skills/task-planning .claude/skills/

# Or user-level (path may vary by setup)
cp -r path/to/this-repo/.claude/skills/task-planning ~/.claude/skills/

Cursor / agent skills (.agents)

mkdir -p .agents/skills
cp -r path/to/this-repo/.agents/skills/task-planning .agents/skills/

Devin

mkdir -p .devin/skills
cp -r path/to/this-repo/.devin/skills/task-planning .devin/skills/

Alternatively, clone this repository into your workspace root so all three paths are present.

Usage

Ask the agent something like:

• “Create an implementation plan for the auth module”
• “Break this PRD into executable tasks”
• “Development plan from DOC to MVP”
• “Update the existing task plan in tasks/”

Italian prompts are supported as well (e.g. piano di implementazione, piano di sviluppo).

Output structure

<workspace>/<objective-kebab-case>/
├── index.json
├── 00-<epic>.json
├── 01-<epic>.json
└── ...

Task object

{
  "id": "TASK-XXX",
  "epic": "Epic name",
  "title": "Short, actionable title",
  "description": "What the task must achieve and why",
  "status": "undone",
  "priority": "P0",
  "type": "setup",
  "what": "Concrete steps to execute",
  "where": "Work area in natural language",
  "filesToCreate": ["src/components/example.tsx"],
  "filesToModify": ["package.json"],
  "expected": "Verifiable acceptance criteria",
  "dependsOn": ["TASK-000"],
  "notes": "Operational notes"
}

Field	Notes
status	done, undone, in_progress, blocked, cancelled
priority	P0 blocking · P1 required · P2 optional
type	setup, infra, db, auth, storage, ui, page, flow, security, audit, notification, test, deploy, ci, docs, quality, performance
filesToCreate / filesToModify	Relative paths; empty arrays when N/A or external service only

Planning principles

• Full coverage — setup, infra, data, security, UI, tests, deploy, docs — not only application code
• Ordered epics — execution order via 00-, 01-, …
• Real dependencies — no P0 waiting on P2
• Verifiable expected — commands, tests, or observable state
• No secrets in task files — env var names only
• Source of truth — PRDs and confirmed decisions; open questions when decisions are missing

Executing tasks from a plan

1. Read index.json and the relevant epic file
2. Pick the first undone task whose dependsOn are satisfied (or the one you name)
3. Set status to in_progress
4. Implement against filesToCreate / filesToModify
5. Check expected
6. Set done or blocked (with a note)

Validate JSON plans

PowerShell (Windows):

Get-ChildItem -Path "<folder>\*.json" | ForEach-Object {
  try {
    $json = Get-Content -Raw $_.FullName | ConvertFrom-Json
    $count = if ($json -is [array]) { $json.Count } else { 1 }
    Write-Output "$($_.Name): OK ($count)"
  } catch {
    Write-Output "$($_.Name): ERROR - $($_.Exception.Message)"
  }
}

Python (cross-platform):

for f in <folder>/*.json; do
  python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(f'{sys.argv[1]}: OK ({len(d) if isinstance(d,list) else 1})')" "$f" \
    || echo "$f: ERROR"
done

License

MIT © Bogdan Nistor — see LICENSE. Use and adapt freely.