Skip to content
mcp/skillhub

Agent Skill

Planning With Files skill

planning-with-filesOthmanAdi/planning-with-files.kiro/skills/planning-with-files/SKILL.md

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; Kiro skill instructions and steering state read selected project planning context. Recovery reads project planning files and their timestamps only, not agent transcript stores. This adapter registers no Stop hook, never requests continuation, and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

28kMIT

always on

96 tokname + description

once used

1,839 tokSKILL.md body

bundled files

125 scripts

repo stars

28kGitHub

Install the Planning With Files skill

Skills CLI (Claude Code, Codex, Cursor and others)

npx skills add https://github.com/OthmanAdi/planning-with-files --skill planning-with-files

Claude Code, by hand (all projects)

git clone --depth 1 https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files
mkdir -p ~/.claude/skills
cp -R /tmp/planning-with-files/.kiro/skills/planning-with-files ~/.claude/skills/planning-with-files

For one project only, copy the folder into .claude/skills/ in that project instead. The agent picks it up when a task matches its description.

What it costs your context

Agent Skills load in three steps. Tokens counted with the o200k tokenizer; your model's count will differ a little.

WhenWhat loadsCost
Every sessionName and description96 tok
When the agent uses itThe SKILL.md instructions1,839 tok
Only if opened12 bundled files (22 KB)varies

Until it is used, planning-with-files costs about 14× less than the median MCP server we measured (1,362 tokens on every turn). Installing all 18 skills from OthmanAdi/planning-with-files would load 2,468 tokens of descriptions. Skills vs MCP study

Checks

  • Ships scripts the agent can run. Read them before installing.

Pre-approved tools (allowed-tools): shell, read, write. The agent can use these without asking while the skill is active.

Checked 2026-10-22 · method

What's inside

The headings of its SKILL.md. Read the full file on GitHub.

  • Planning with Files (Kiro)
  • STEP 0 — Bootstrap (once per workspace)
  • STEP 1 — Persistent reminder (after skill activation)
  • STEP 2 — Read plan every turn (while active)
  • STEP 3: Project-file catchup (after a long gap or suspected drift)
  • Optional — Phase checklist
  • The Core Pattern
  • File Purposes
  • Critical Rules
  • 1. Create Plan First
  • 2. The 2-Action Rule
  • 3. Read Before Decide
  • 4. Update After Act
  • 5. Log ALL Errors
  • 6. Never Repeat Failures
  • 7. Continue After Completion
  • The 3-Strike Error Protocol
  • Read vs Write Decision Matrix
  • Scripts
  • Advanced Topics
  • Security Boundary
  • Anti-Patterns
  • When to use

More skills from OthmanAdi/planning-with-files

All skills in this repo
  1. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k22117 tok idle · 7,643 in use
  2. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k13117 tok idle · 2,151 in use
  3. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k13117 tok idle · 1,699 in use
  4. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k31117 tok idle · 8,278 in use
  5. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; agent instructions read selected project planning context when invoked. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. This adapter registers no lifecycle or Stop hook, never requests continuation, and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k12120 tok idle · 2,550 in use
  6. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k17117 tok idle · 1,724 in use
  7. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k17117 tok idle · 1,709 in use
  8. planning-with-filesOthmanAdi/planning-with-files

    Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

    28k17117 tok idle · 1,698 in use