How to use the Planning with Files (Kiro) agent skill

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

An agent skill is a folder with a SKILL.md file that describes when and how an AI agent should work. The agent loads the skill when a task matches the skill's description, so you do not have to paste instructions each time.

This skill works like a plan kept on disk. The agent keeps task_plan.md (goal, phases and status), findings.md (research and decisions) and progress.md (a log of actions, test results and errors) inside your project. Because the files are on disk, the plan survives when the chat context grows long or is reset. Each turn, the agent re-reads the plan so it stays on track.

• task_plan.md: phases, progress and decisions, updated after each phase
• findings.md: research and discoveries, updated after any discovery
• progress.md: session log, test results and errors, updated throughout the session

Install the skill from the download

Download the ZIP from this page and unzip it so the planning-with-files folder sits in your skills directory. Use ~/.claude/skills/ for a personal install, or a project's .claude/skills/ folder to share it with one repository.

You can also upload the skill in the Claude apps under Settings, then Capabilities, then Skills.

Note that the skill's own instructions and helper paths use the .kiro/ layout (for example .kiro/skills/planning-with-files/ and .kiro/plan/). If you install it under .claude/skills/, adjust those paths or check that the bootstrap command below finds the scripts before relying on it.

Create the planning files in your workspace

Run the bootstrap once from the workspace root. It creates the three planning files in .kiro/plan/ and a steering file at .kiro/steering/planning-context.md. The steering file uses inclusion: auto and live references to the plan files, so the Kiro editor keeps them in view. Bootstrap is idempotent: existing files are not overwritten.

On Windows, use the PowerShell version of the same script. In Kiro you can also import the planning-with-files folder as a workspace skill through Agent Steering and Skills, then Import a skill.

• Creates .kiro/plan/task_plan.md, findings.md and progress.md
• Creates .kiro/steering/planning-context.md
• Existing files are left alone

Trigger the skill with a natural request

The skill activates when a task matches its description: research or work needing five or more tool calls. You do not need special syntax. Ask for a multi-step job in plain language and the agent should create or reuse a plan before substantive work.

Once active, the agent appends a short reminder to the end of its replies that says to read .kiro/plan/task_plan.md and .kiro/plan/progress.md before each turn. If you come back after a long gap, you can ask the agent to resume the task or check the current phase.

• Example: Research the options for caching in this service and write up a recommendation.
• Example: Refactor the export module in phases and keep a plan so we can pick it up tomorrow.
• Example: Continue the migration task and show me the current phase.
• Example: Check where we are on the plan and what is still pending.

Check the plan and recover after a gap

When the chat has been reset or you suspect the agent has drifted from the plan, run the catch-up helper from the workspace root. It reports the planning files' timestamps and summaries, then the agent should reconcile the plan with the actual codebase. The helper does not read agent transcript stores. It needs Python 3.

The phase checker verifies that the plan's phase markers are formatted correctly. Each phase must use the form ### Phase N: Name with exactly one status line (pending, in_progress or complete). It checks format only, not whether the task is actually finished.

• Phase headings must follow ### Phase N: Name
• Each phase needs exactly one **Status:** line
• Validation checks format, not task completion

Safety notes: scripts, network and sensitive data

The skill runs scripts: bootstrap.sh, check-complete.sh and session-catchup.py. According to the skill's description, it has no network upload path and uses no network. It registers no Stop hook, never requests continuation, and never runs commands declared in Markdown. Hooks are not bundled, because project-level hooks would affect every chat in the workspace.

The plan files are plain text written into your workspace. They may capture details from the project, and they can be committed to version control. For sensitive projects, review the files before committing or keep them out of the repository.

• Runs scripts: yes (shell or PowerShell, plus Python 3 for session-catchup.py)
• Uses network: no
• Needs read and write access to the workspace
• Plan files are editable and visible, so review them before sharing

Tips for getting the most from it

Keep the plan current. The skill's rules ask the agent to update status after each phase, log every error and avoid repeating a failed action. If the plan falls behind, ask the agent to update it before continuing.

If you add work after all phases are complete, ask for new phases. The agent should add them to task_plan.md and log a new session entry in progress.md. If a plan file fails validation, the skill asks for it to be reported for review rather than rewritten automatically.

• Use it for work that needs five or more tool calls; skip it for quick questions
• Review plan files before committing them
• Read the plan before major decisions
• Validate the plan after changing phase structure