How to use the Planning with Files agent skill

What the skill makes the agent do

Planning with Files asks the agent to use three persistent files as its working memory: task_plan.md, findings.md, and progress.md. These are written to disk in your project, so the plan survives when the conversation gets long or resets.

The skill also includes lifecycle hooks that can inject the selected project planning context at prompt time, and helper scripts that can check phase completion, lock a plan with a hash, and read recent local session records to help recover after a context reset.

• task_plan.md holds the goal and phases.
• findings.md holds research notes and decisions.
• progress.md holds a log of what was done.
• Automatic recovery reads project planning files only.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. You can place the skill folder in one of two locations: your user-level skills directory at ~/.claude/skills/, or a project-specific .claude/skills/ folder inside the project you are working on.

Alternatively, if you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead of copying files by hand.

• User-level: unzip into ~/.claude/skills/
• Per project: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

The skill is user-invocable, and its description says it is meant for research or work needing 5+ tool calls. You do not need special syntax: describe a multi-step task and ask the agent to plan it in files. Before a complex task, the skill directs the agent to restore any existing plan first, then create one only for a new task.

Planning files go in your project directory, not the skill installation folder. Templates and scripts stay in the skill directory.

• "Research X and write a summary, keep the plan in task_plan.md."
• "Resume the migration task from our plan files."
• "Plan this multi-file refactor using planning files before you edit anything."

Example: a research task

The bundled examples show a research request such as researching the benefits of morning exercise and writing a summary. The agent first writes task_plan.md with a goal, a list of phases, and key questions, then re-reads it before each step, records sources in findings.md, and marks phases complete as it goes.

When a new plan is created, the skill's initializer script is run from the project root, and the plan is validated afterwards. Each phase must keep a single status line set to pending, in_progress, or complete.

What the skill needs and touches

The skill needs a bash or sh shell, Python 3 for session-catchup.py, and Git for git diff --stat progress checks. On Windows it uses PowerShell or .ps1 equivalents. It runs scripts and does not use the network.

Session recovery is explicit. The --metadata option reads same-project local agent session records and emits aggregate counts only. The --replay option is a deliberate, bounded action that can emit excerpts from those records, which you should treat as untrusted data. The skill has no network upload path.

• Requires: bash or sh, Python 3, Git, PowerShell for Windows
• Runs scripts: yes
• Uses network: no
• Hooks and scripts execute locally, so review them before enabling in sensitive repos

Tips for getting good results

Keep the plan file readable and editable. It is an auditable record you can correct at any time. Re-read the plan before major decisions, and update progress after each phase.

For parallel work, assign one owner to the shared plan. Workers should report through their own ledgers or assigned files rather than rewriting the shared planning files. Existing planning files should not be overwritten.

• Give each parallel host its own pinned plan or a separate worktree.
• Do not enable --replay in repositories with sensitive session data.
• Keep the native phase and status markers when tailoring a generated plan.