Skip to content
Get packs

Planning with Files

Keeps a persistent markdown plan, findings and progress log on disk so long multi-step agent tasks stay on track.

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

What it does

When installed, the agent keeps three plain markdown files in your project (task_plan.md, findings.md, progress.md) as a working memory on disk. It re-reads them at the start of a task or session so it can resume after context is lost, and updates them as phases complete. Optional Hermes adapter hooks can inject the active plan into each turn and report progress.

Great for

  • Developers running long agent coding or research tasks that take many tool calls
  • People who lose track when an AI session is interrupted or the context window fills up
  • Users of the Hermes agent who want per-project plan files and status commands

Skip it if

  • Quick one-off questions or small edits, where the planning overhead adds nothing
  • Projects where you do not want extra planning files written into the repository, since the skill creates them in the project root
  • Sensitive sessions: the optional --metadata and --replay session-catchup commands read local agent session records of the same project, so only enable them if you are comfortable with that access

Try asking

  • “Plan a multi-step research task and keep the findings in findings.md as you go”
  • “Resume yesterday's refactor by reading task_plan.md and progress.md before continuing”
  • “Start a new planned project with the analytics template”
  • “Check which phases of the current plan are still in progress”
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 13 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

  • Ask the agent to create the plan before starting complex work, then say 'continue the plan' in later sessions so it re-reads the files first.
  • Keep the planning files in the project root and review them; they are plain markdown you can edit yourself.
  • Leave the optional session-catchup --metadata command off unless you want the agent to summarise recent local session activity.

What's inside

  • plan-inventory.md
  • scripts/check-complete.sh
  • scripts/check-continue.sh
  • scripts/init-session.sh
  • scripts/session-catchup.py
  • scripts/set-active-plan.sh
  • scripts/sync-ide-folders.py
  • SKILL.md
  • templates/analytics_findings.md
  • templates/analytics_task_plan.md
  • templates/findings.md
  • templates/progress.md
  • templates/task_plan.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.