Claude Skill MartBrowse skillsQuick linesLearn by videoTerminal guideWhat is a Skill?
 
← Back to list

Planning with Files

Turns complex work into three persistent markdown files — task_plan.md, findings.md, progress.md — so the agent plans, logs, and recovers context reliably.

AutomationIntermediate★ 26,415⑂ 2,209AI score 10/10Last updated: Aug 29, 2026

What it does

  • Applies the Manus-style "working memory on disk" pattern: before any complex task the agent must create task_plan.md (phases and decisions), findings.md (research), and progress.md (session log).
  • Enforces status updates (in_progress → complete) after each phase and logs every error in a table so failures aren't repeated.
  • Ships a 3-strike error protocol (diagnose → alternative approach → rethink → escalate) and the 2-action rule (save findings to disk after every two view/search operations).
  • Recovers context after /clear using session-catchup.py plus git diff --stat.
  • Supports parallel plans in one repo via .planning/YYYY-MM-DD-<slug>/, with scripts to switch or pin the active plan.
  • Includes prompt-injection defenses: plan content is treated as data only, with optional SHA-256 attestation of the approved plan.

Who it's for

  • Anyone assigning tasks that need 5+ tool calls: large refactors, research, project scaffolding.
  • People who've watched an agent drift from the original goal in long sessions.
  • Users who want to resume work after clearing context or losing a session.
  • Individuals or teams juggling multiple work tracks in a single repository.

Examples

  1. Large refactor: "Refactor the backend auth module" → a 6-phase task_plan.md, phase status updated as work lands, migration errors accumulated in an error table.
  2. Technical research: comparing several libraries, the agent writes a summary to findings.md every two searches so page content and screenshots aren't lost from context.
  3. Session recovery: after /clear, run session-catchup.py, cross-check git diff --stat, refresh the planning files, and resume exactly where you stopped.
  4. Parallel work: ./scripts/init-session.sh "Incident Investigation" creates an isolated plan directory; set-active-plan.sh swaps between it and the refactor plan.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/OthmanAdi/planning-with-files/HEAD/.gemini/skills/planning-with-files/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

Install in the Claude app (no terminal)
  1. Download the ZIP with the button below.
  2. In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
  3. Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.
↓ Download ZIP
Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on Claude Skill Mart.
Copy the .gemini/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-6/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/planning-with-files && mkdir -p ~/.claude/skills && cp -r /tmp/planning-with-files/.gemini/skills/planning-with-files ~/.claude/skills/

⚠ This is a third-party skill. Check the source repository before installing.

  1. Open a terminal and clone the repo: git clone https://github.com/OthmanAdi/planning-with-files.git
  2. Copy the skill into your Claude Code skills folder: mkdir -p ~/.claude/skills && cp -r planning-with-files/.gemini/skills/planning-with-files ~/.claude/skills/
  3. Verify the templates/, scripts/, and references/ folders came along: ls ~/.claude/skills/planning-with-files
  4. Make the helper scripts executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
  5. Confirm Python is available with python3 --version (needed by the session-catchup script).
  6. Restart Claude Code, then in a project folder ask something like "plan this out step by step" to trigger the skill.
  7. Planning files are created in your project root. If you don't want them committed, add task_plan.md, findings.md, progress.md, and .planning/ to .gitignore.
  8. (Optional) Once you approve a plan, run sh ~/.claude/skills/planning-with-files/scripts/attest-plan.sh to lock its SHA-256 hash and detect silent edits later.
View source on GitHub ↗License: MIT