Skip to content
mcp/skillhub

Agent Skill

Planning With Files skill

planning-with-filesOthmanAdi/planning-with-files.opencode/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; 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.

28kMIT

always on

117 tokname + description

once used

2,151 tokSKILL.md body

bundled files

2113 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/.opencode/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 description117 tok
When the agent uses itThe SKILL.md instructions2,151 tok
Only if opened21 bundled files (266 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.

Pre-approved tools (allowed-tools): Read, Write, Edit, Bash, Glob, Grep. 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
  • FIRST: Restore Project State
  • OpenCode Notes
  • 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
  • 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
  • Advanced Topics
  • Anti-Patterns

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 · 1,699 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.

    28k31117 tok idle · 8,278 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; 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
  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; 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
  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,709 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,698 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; 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.

    28k12118 tok idle · 2,514 in use