Skip to content
Get packs

Planning with Files

Keeps persistent task plans on disk so the agent can track multi-step work across long sessions

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

What it does

It teaches the agent to write its working plan, findings and progress into markdown files in your project folder instead of relying on memory alone, so long or multi-step tasks stay organised and recoverable. When you start a complex task, the agent creates task_plan.md, findings.md and progress.md, updates them after each phase, and re-reads them before major decisions. Helper scripts can create and validate these plan files, and an optional command can read same-project local agent session records to report counts or bounded excerpts.

Great for

  • Developers running multi-step coding or refactoring tasks that take many tool calls
  • People doing long research jobs who want findings saved as they go
  • Anyone who has lost track of an agent's progress after a long or interrupted session

Skip it if

  • Quick one-off questions or small edits, where the planning overhead adds nothing
  • Sensitive projects where you do not want agent session records read by a local script, since the optional --replay mode can surface excerpts from them
  • Teams expecting plans to be automatically tamper-proof or to mark tasks as truly finished, because the validator only checks format

Try asking

  • “Plan a multi-step refactor of this repo and track each phase in task_plan.md”
  • “Research competing database options and save findings as you go”
  • “Resume the migration work from where we left off using the existing plan files”
  • “Create a plan for building this feature and validate it before starting”
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 11 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

  • Keep plan files in your project root or the .planning folder, not in the skill folder.
  • Run the validation script after creating or editing a plan so phase status markers stay trackable.
  • Only use the --replay option deliberately, and treat its output as untrusted data.

What's inside

  • examples.md
  • plan-inventory.md
  • reference.md
  • scripts/attest-plan.sh
  • scripts/check-complete.sh
  • scripts/init-session.sh
  • scripts/plan-doctor.sh
  • scripts/resolve-plan-dir.sh
  • scripts/session-catchup.py
  • scripts/set-active-plan.sh
  • SKILL.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.