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

Planning with Files

Keeps task_plan.md, findings.md, and progress.md on disk so the agent never loses its goal or progress across long, multi-step work.

AutomationIntermediate★ 27,074⑂ 2,254AI score 10/10Last updated: Sep 22, 2026

What it does

  • Creates and maintains task_plan.md (phases and decisions), findings.md (research), and progress.md (session log) inside your project directory.
  • Uses lifecycle hooks (UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact) to re-inject plan context, so state survives compaction and session restarts.
  • Enforces hard rules: save findings after every 2 view/search operations, re-read the plan before decisions, log every error, and escalate to the user after 3 failed attempts.
  • Ships helper scripts: init-session.sh, check-complete.sh, set-active-plan.sh --list, and session-catchup.py --metadata/--replay for state recovery.

Who it's for

  • Anyone running research, refactor, or build tasks that need 5+ tool calls.
  • Developers frustrated by the agent forgetting the original goal once context fills up.
  • Teams splitting work across sessions or multiple workers (one orchestrator plus worktrees).

Example uses

  1. Large codebase migration: build a phased plan, flip each phase in_progress → complete, and accumulate an error table so failures aren't repeated.
  2. Competitive research: after every two web lookups, dump key takeaways into findings.md so screenshot/PDF context isn't lost.
  3. Resuming days later: run set-active-plan.sh --list, pin the PLAN_ID, read the three planning files, and continue exactly where you stopped.

· · · 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/.codex/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 .codex/skills/planning-with-files folder from the GitHub repo OthmanAdi/planning-with-files into my ~/.claude/skills/othmanadi-planning-with-files-2/.
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/pwf && mkdir -p ~/.claude/skills && cp -r /tmp/pwf/.codex/skills/planning-with-files ~/.claude/skills/ && rm -rf /tmp/pwf

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

  1. Open a terminal.
  2. Clone the repo to a temp folder: git clone https://github.com/OthmanAdi/planning-with-files.git /tmp/pwf
  3. Create the skills folder: mkdir -p ~/.claude/skills
  4. Copy the skill: cp -r /tmp/pwf/.codex/skills/planning-with-files ~/.claude/skills/
  5. (If you also use Codex, copy the same folder into ~/.codex/skills/.)
  6. Make scripts executable: chmod +x ~/.claude/skills/planning-with-files/scripts/*.sh
  7. Verify Python is available with python3 --version (needed by session-catchup.py).
  8. If you installed to a non-standard path, add export PWF_SCRIPT_DIR=~/.claude/skills/planning-with-files/scripts to your shell config.
  9. Restart Claude Code, go to your project root, and ask it to "track this task with planning files" to confirm the hooks fire.
View source on GitHub ↗License: MIT