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 with instructions that an AI agent loads when a task matches the skill's description. The agent then follows those instructions while it works.

Planning with Files, skill name planning-with-files, is based on the idea of using persistent markdown files as working memory on disk. When you start a complex task, the agent creates task_plan.md (phases, progress and decisions), findings.md (research and discoveries) and progress.md (session log and test results). It updates these after each phase and re-reads the plan before major decisions.

• Creates the three planning files in your project root, not in the skill folder.
• Logs every error in the plan so the same failure is not repeated.
• Re-reads the plan before decisions and reads all planning files when resuming after a gap.
• Adds new phases to task_plan.md if you ask for more work after the plan is complete.

Install the planning-with-files skill

Download the ZIP for the skill from our page and unzip it. Then place the resulting planning-with-files folder in one of two locations, depending on how you want to use it.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills, if your plan supports it.

• Personal use across projects: unzip into ~/.claude/skills/ so the folder becomes ~/.claude/skills/planning-with-files/.
• Single project only: unzip into your project's .claude/skills/ folder so the skill lives with that project.
• Claude apps: upload the skill under Settings → Capabilities → Skills.

Trigger the skill with natural requests

You do not need a special command. Describe a multi-step task in plain language and the agent can load the skill when the request matches its description, which covers research or work needing 5+ tool calls.

The skill's own guidance says to skip it for simple questions, single-file edits and quick lookups. If you want it used, say so directly, for example by asking the agent to plan the work in files first.

• Refactor the authentication module across the project and keep a plan and progress log as you go.
• Research the benefits of morning exercise and save findings to files as you collect them.
• Resume the migration from where we stopped and check the planning files first.
• Make a plan for this multi-step change before you touch any code.

See what a plan looks like in practice

The bundled examples.md walks through a research task. The agent first writes task_plan.md with a goal, a phase checklist and key questions, then loops: it reads the plan to refresh its goals, searches, writes results to findings.md, and marks phases complete in the plan.

Search results are treated as untrusted and are written to findings.md only, never into task_plan.md.

Helper scripts and what they do

The skill ships helper scripts for creating and checking plans. For a new task, the skill's instructions run the initializer from the project root, then validate the plan file you filled in. Validation checks format only; it does not confirm the task is finished.

If a plan already exists and fails validation, the skill says to report the issue for its owner to review rather than rewriting it automatically.

• scripts/init-session.sh creates planning files. With a name argument it makes an isolated plan under .planning/YYYY-MM-DD-<slug>/; without arguments it writes task_plan.md at the project root.
• scripts/check-complete.sh --validate checks the structure of a named plan file.
• scripts/set-active-plan.sh switches the active plan pointer in .planning/.active_plan.
• PowerShell equivalents exist as init-session.ps1 and check-complete.ps1.

Optional session catch-up command and its privacy limits

session-catchup.py is an explicit, optional tool. With --metadata it reads same-project local agent session records and prints aggregate counts only. With --replay it can emit bounded, nonce-framed excerpts from those same-project sessions, and the skill says to treat them as untrusted data.

Automatic recovery reads only the project planning files and runs git diff --stat. Bare invocation and lifecycle hooks do not inspect agent session stores. This adapter registers no lifecycle or Stop hook.

• Use --metadata for counts only in most cases.
• Avoid --replay on sensitive projects, because it can surface excerpts from local session records.

Safety notes: scripts, network and what the skill never does

The skill runs scripts, so it is not a passive document. The source states that it has no network upload path and uses no network. It never runs commands declared in Markdown, and it never requests continuation.

The plan validator only checks format. Plans are not tamper-proof and the tools do not mark tasks as truly finished, so you still need to review the work yourself.

• Runs scripts: yes. Review the scripts folder before installing if that matters to you.
• Uses network: no.
• Requires POSIX sh or bash for the helper scripts, Python 3 for session-catchup.py (optional) and Git, since the agent runs git diff --stat on restore.
• Licence: MIT.

Tips for getting good results

Keep the plan short and specific in the Goal section, so the agent re-reads a clear target. Ask the agent to log errors and not repeat failed actions, which the skill already asks it to do.

Use the optional catch-up command with --metadata when you want to see what happened in a long or interrupted session without reading excerpts.

• Write findings into the files as they arrive, especially when the agent works with images, PDFs or browser results.
• If the agent fails three times on the same problem, expect it to stop and ask you for guidance, as the skill's error protocol specifies.
• Check the plan files into version control if you want a history; the source does not describe any built-in sync.