How to use the Planning with Files agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder containing a SKILL.md file and supporting scripts or templates. When it is installed, the agent reads the SKILL.md instructions when a task matches the skill's description. This skill is described for research or work needing 5+ tool calls.

When installed, the agent keeps three plain markdown files in your project root: task_plan.md, findings.md and progress.md. It re-reads them at the start of a task or session so it can resume after context is lost, and it updates them as phases complete.

• task_plan.md: the phased roadmap, with each phase marked pending, in_progress or complete.
• findings.md: requirements, research results, technical decisions and issues encountered.
• progress.md: a running log of what was done and what happened next.

Install Planning with Files in Claude

Download the ZIP from this page and unzip it. For a personal install, place the planning-with-files folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill from there.

• Personal install: ~/.claude/skills/planning-with-files/
• Project install: .claude/skills/planning-with-files/ inside your project

Install it for the Hermes agent (optional)

If you use the Hermes agent, lifecycle automation comes from an adapter plugin in .hermes/plugins/planning-with-files/. The skill's own notes give these two commands to install and enable it.

Hermes Desktop uses the same plugin. Install it as a user plugin, and each Desktop session pins its project folder.

How to trigger the skill with natural requests

Ask for a multi-step task in plain language and mention that you want planning files kept. The skill is meant for work that takes many tool calls, so a short question is unlikely to need it.

On a new task, the skill's quick start asks the agent to create the three planning files before complex work begins, re-read the plan before decisions, and update it after each phase. Note that the skill creates these files in your project root, not in the skill folder.

• Example request: "Refactor the billing module across these five services. Keep a plan and track progress in the project files."
• Example request: "Research the three vector databases in this list and summarise findings. Use planning files so we can pick this up later."
• Example request: "Pick up where we left off on the migration plan."

Resume an interrupted session

When a session is interrupted or the context window fills up, the agent's first step is to check whether planning files exist and read them. It then runs git diff --stat to see code changes that may not yet be recorded in the planning files.

On Hermes, the status commands name the active plan when you have several. The skill's notes list /pwf-status and /plan-status for this.

• Automatic recovery reads project planning files only.
• git diff --stat requires Git to be installed.

Check plan format with the helper scripts

For a new task the agent runs the initializer before implementation, then validates the plan file. Validation checks format only. It does not confirm that the task is complete.

Each phase must use the heading form ### Phase N: Name with exactly one status line: pending, in_progress or complete. A checklist alone is not trackable.

• Reuse existing plans without overwriting them.
• If an existing plan fails validation, report the issue rather than rewriting it automatically.

Safety notes: scripts, session records and network

The skill runs scripts, so it is not just text. Its requirements list says it runs scripts and does not use the network. The skill states it has no network upload path.

The optional session-catchup.py command with --metadata reads local agent session records from the same project and prints aggregate counts only. The --replay option prints bounded excerpts framed with a nonce and should be treated as untrusted data. Only enable these if you are comfortable with that access to your local session records.

Optional gated mode can ask the host to continue only when the host supports it. It never runs commands declared in Markdown.

• The skill creates planning files in your project root, so do not use it where you do not want extra files in the repository.
• Read the scripts before running them in sensitive projects.

Tips for getting the most out of it

Use the skill for long tasks and skip it for small edits, where the overhead adds nothing. Keep the phase headings intact when you tailor a generated plan, because the validator depends on them.

On native Windows, the helper scripts need PowerShell or Python 3, and Python 3 is needed for session-catchup.py and sync-ide-folders.py.

• Keep phase headings in the ### Phase N: Name form.
• Update the status line each time a phase changes.
• Run the validator after you change phase structure.