Skip to content
Get packs

Planning with Files

Gives the agent persistent markdown planning files on disk for multi-step work, with optional plan hooks.

Source Download skill
Repository
OthmanAdi/planning-with-files
Stars
27,822
Licence
MIT
Files
15 files

What it does

This skill teaches an AI coding agent to keep its working plan in files inside your project (task_plan.md, findings.md, progress.md) instead of relying only on its short-term memory. Lifecycle hooks can inject the selected plan back into the agent's context at prompt time, and helper scripts can check phase completion, lock a plan with a hash, and read recent local session records to recover after a context reset.

Great for

  • Developers running long, multi-step agent tasks (5+ tool calls) who lose track of progress after context resets
  • Teams running parallel agent work that need a clearly owned shared plan
  • Users who want an auditable plan file they can read and edit

Skip it if

  • Quick one-off questions or small edits, where the planning overhead adds no value
  • Projects where you do not want agents writing files or running shell scripts, since hooks and scripts execute locally
  • Sensitive repositories if you enable --replay, because it surfaces excerpts from local agent session records into context

Try asking

  • “Plan a multi-file refactor of our API and track progress across phases in task_plan.md”
  • “Resume yesterday's research task by restoring the selected plan and recent progress”
  • “Create a findings.md summarising what we learned while debugging the build failure”
  • “Lock the finished plan with an attestation so later edits are flagged as tampered”
Step-by-step guide: how to use Planning with FilesInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 15 original files, the MIT licence and an attribution note.

    planning-with-files.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip planning-with-files.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip planning-with-files.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Run the initializer script before starting a complex task so the plan files follow the expected structure
  • Use --metadata rather than --replay for routine recovery, since replay exposes excerpts of past sessions
  • Set PLAN_ID when several named plans exist so the agent does not pick the wrong one

What's inside

  • references/examples.md
  • references/plan-inventory.md
  • references/reference.md
  • scripts/attest-plan.sh
  • scripts/check-complete.sh
  • scripts/gate-stop.sh
  • scripts/init-session.sh
  • scripts/ledger-summary.sh
  • scripts/plan-doctor.sh
  • scripts/resolve-plan-dir.sh
  • scripts/session-catchup.py
  • scripts/set-active-plan.sh
  • scripts/skill-hook.sh
  • SKILL.md
  • templates/analytics_findings.md

Redistributed unmodified from OthmanAdi/planning-with-files under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.