Skip to content
mcp/skillhub

Agent Skill

Planning With Files skill

planning-with-filesOthmanAdi/planning-with-files.gemini/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; Gemini 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. The session-end hook reports status only; it does not request continuation or run commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

28kMIT

always on

118 tokname + description

once used

2,514 tokSKILL.md body

bundled files

2012 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/.gemini/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 description118 tok
When the agent uses itThe SKILL.md instructions2,514 tok
Only if opened20 bundled files (219 KB)varies

Until it is used, planning-with-files costs about 12× 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.

Checked 2026-10-22 · method

What's inside

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

  • Planning with Files
  • FIRST: Restore Project State
  • Important: Where Files Go
  • Quick Start
  • 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
  • The 5-Question Reboot Test
  • When to Use This Pattern
  • Templates
  • Scripts
  • List saved plans
  • Parallel task workflow
  • Advanced Topics
  • Security Boundary

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