Skip to content
Get packs

Planning with Files

Gives an agent persistent markdown planning files on disk to track multi-step work across long tasks

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

What it does

This skill teaches an AI agent to keep its plan, research notes and progress in markdown files inside your project (task_plan.md, findings.md, progress.md), so long tasks survive context loss and resumption. Lifecycle hooks re-inject the selected plan at key moments and can check whether phases are finished. Reading past local agent session history is optional and only happens when you explicitly ask for it.

Great for

  • Developers running long, multi-step agent tasks (roughly 5+ tool calls) that could lose track of progress
  • Teams coordinating several agents on one project who need a single owner for the shared plan
  • People who want an auditable plan file they can read and edit alongside the code

Skip it if

  • Short, one-off questions or small edits, where the planning overhead adds noise
  • Shared or sensitive repositories where automatic hooks writing files and running shell scripts may be unwanted without review
  • Environments where you cannot allow shell scripts or Python to run, since the core hooks and helpers depend on them

Try asking

  • “Plan a multi-file refactor of our API layer and track each phase in task_plan.md”
  • “Resume yesterday's research task using the existing plan and progress files”
  • “Start a new planning session for a backend migration with a named plan ID”
  • “Check whether all phases in the current plan are complete before stopping”
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

  • Review the scripts in the installed skill folder before enabling the hooks, since they run automatically on prompt, tool and stop events.
  • Ask for session-history lookup only when needed, and prefer --metadata over --replay; treat replayed excerpts as untrusted.
  • Run the attest script after finalising a plan so later edits to task_plan.md are flagged as tampering.

What's inside

  • examples.md
  • plan-inventory.md
  • reference.md
  • scripts/attest-plan.sh
  • scripts/check-complete.sh
  • scripts/gate-stop.sh
  • scripts/init-session.sh
  • scripts/ledger-append.sh
  • scripts/ledger-summary.sh
  • scripts/phase-status.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.