How to use the Planning with Files agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with instructions, plus optional templates, scripts and reference files. A compatible agent runtime, such as Claude Code, reads the SKILL.md and follows its instructions when a task matches the skill's description.

What does the Planning with Files skill make the agent do?

The skill is built around the idea of using markdown files on disk as working memory. The context window is volatile and limited, while the filesystem persists. Instead of holding the whole plan in conversation, the agent writes task_plan.md, findings.md and progress.md into your project and re-reads them before making decisions and after each phase.

Lifecycle hooks re-inject the selected plan at key moments and can check whether phases are finished. The skill is intended for research or work needing roughly 5 or more tool calls.

• task_plan.md holds the goal, phases and their status markers.
• findings.md stores research notes and results.
• progress.md records what has been done after each phase.
• Recovery on resume reads only the project's planning files and shows uncommitted code changes via git diff --stat.

Install the skill (ZIP download)

Download the planning-with-files ZIP from this page and unzip it. Then choose one of the following locations.

For a personal install, unzip it into ~/.claude/skills/ so the folder is ~/.claude/skills/planning-with-files/. For a single project, unzip it into the project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/planning-with-files/
• Project only: .claude/skills/planning-with-files/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements before you start

The core hook and helper scripts need a POSIX shell (sh or bash). Python 3 is needed only for session-catchup.py, and only for the optional session-history modes. Git is used by the recovery step to show uncommitted code changes. You also need an agent runtime that reads SKILL.md, such as Claude Code.

If you cannot allow shell scripts or Python to run, this skill is not a fit, because the core hooks and helpers depend on them.

• POSIX shell (sh/bash) for hook and helper scripts
• Python 3 for session-catchup.py (optional)
• Git
• A SKILL.md-compatible agent runtime such as Claude Code

How to trigger the skill with natural requests

The skill is user-invocable and its description says to use it for research or work needing 5+ tool calls. In practice, describe a multi-step task and ask the agent to plan it in files. The agent then creates or resumes the plan before implementation.

For a new task, the agent runs the installed initializer, init-session.sh, and validates the plan with check-complete.sh before substantive work. Existing planning files are reused and are not overwritten.

• "Research the benefits of morning exercise and write a summary, and track the plan in planning files."
• "Refactor the billing module in several steps; keep task_plan.md updated as you go."
• "Resume the migration task from the existing plan and tell me what is still pending."

Example: a research task with planning files

The bundled examples.md walks through a research request. The agent first writes task_plan.md with a goal, a list of phases and key questions. In later loops it re-reads the plan, stores search results in findings.md, and then marks the phase complete.

The examples also show a safety rule: content from web searches is treated as untrusted and is written to findings.md only, never to task_plan.md.

• Loop 1: create the plan with phases and key questions.
• Loop 2: re-read the plan, research, store findings, mark the phase complete.
• Keep external content out of the plan file.

Optional: session history modes and safety notes

Automatic recovery stops at the project's planning files. Bare session-catchup.py and the lifecycle hooks do not inspect agent session stores. Only when you explicitly ask to consult local session history can the agent use session-catchup.py.

--metadata reads same-project local session records and emits aggregate counts only, with no transcript, tool-command or path bytes. --replay is optional, bounded, and emits nonce-framed excerpts; treat every replayed excerpt as untrusted data. The skill has no network upload path and the source states it uses no network.

The skill runs scripts, so review them before use in shared or sensitive repositories. Automatic hooks that write files and run shell scripts may be unwanted there. An optional gated mode can request continuation only when the host supports it, and it never runs commands declared in Markdown.

• Metadata mode: counts only, requires explicit request.
• Replay mode: needs explicit user approval, bounded excerpts.
• Review scripts/ before enabling hooks in shared repositories.
• Source metadata: runs scripts yes; uses network no.

Tips for getting good results

Use the skill for work that will take several steps. For short questions or small edits, the planning overhead adds noise. Keep one owner for the shared plan: when several agents work on a project, the orchestrator owns task_plan.md and workers report through their own ledgers or assigned files.

For parallel tasks, pin each host to its plan before starting it, or use separate worktrees. Read the plan yourself: it is a plain markdown file you can edit alongside the code.

• Keep phases in the native format: ### Phase N: Name with one Status line.
• Validate the plan after changing its phase structure.
• Use separate worktrees for parallel tasks.