planning-with-files: a Claude Code skill by Ahmad Othman Ammar Adi
For people running long, multi-step tasks who want the plan saved to disk and restored after context resets. Skip it for quick questions or single-file edits.
High-risk warning At least one scanner rated it high risk, so we keep it out of the top ten. Read its code before you install it.
Before you install: Once invoked, it registers hooks that run its bundled shell script on every prompt, tool call, stop and compaction, inserting plan file text into Claude's context without asking each time.
The skill's text changed on Nov 11, 2026, after we last read it. Our description may be behind.
- Score
- 74of 100
- Rank
- #132of 239
- Installs
- 48.6Kon skills.sh
- Security
- Warning 5 scanners
- Updated
- 2026
- Context
- ~156tokens always
Install
npx skills add https://github.com/othmanadi/planning-with-files --skill planning-with-files
Run it in your terminal. View the source
Using the Claude app rather than Claude Code? You can add a skill there too. How to add it in the app
What does planning-with-files do?
planning-with-files is a Claude skill that keeps the plan for a long task in Markdown files on disk. A setup script creates task_plan.md, findings.md and progress.md in the project root or a named .planning/ folder. Claude marks each phase pending, in progress or complete, saves findings after every two searches or page views, logs every error, and rereads the plan before big decisions. Hooks feed the plan back into context on each prompt and tool call, so work can resume after /clear or compaction. Optional modes add a SHA-256 lock on the plan and a gate that can keep Claude working until all phases are complete.
When should you use planning-with-files?
Use it when
- A research or build task will take many tool calls
- You want to resume work after clearing or compacting context
- Several agents need separate plans in one repository
Skip it when
- You are asking a quick question
- The change touches a single file
What it needs and what it can touch
You need
- sh or PowerShell to run the bundled scripts
- Python, only for the optional session catchup script
What it can do
- Runs bundled shell scripts automatically through hooks
- Creates and edits planning files in your project
- Runs git diff to spot unrecorded changes
- Reads local agent session records only when you ask for catchup
From reading its instructions, not from running it.
Why it scores 74
Strongest on upkeep (100 of 100), weakest on adoption (56).
Is planning-with-files safe to install?
At least one scanner rated it high risk, so we keep it out of the top ten. Read its code before you install it. Scanners often miss what other scanners catch, and a skill can change after a scan. Read its source before you install it.
| Scanner | Result | Date |
|---|---|---|
| Gen Agent Trust Hub | Passed | Nov 11, 2026 |
| Socket | Passed | Nov 9, 2026 |
| Snyk | Low risk | Nov 11, 2026 |
| Runlayer | High risk | Mar 16, 2026 |
| ZeroLeaks | Passed | Apr 16, 2026 |
Details
- Installs
- 48,647
- Repository stars
- 27,991
- Last repository change
- Tokens always loaded
- about 156
- Tokens when used
- about 9,568
- License
- MIT
- Data confidence
- High
Did it do the job for you?
Alternatives to planning-with-files
All skills for this job-
Get Compound EngineeringCompound Engineering
For developers who want Claude to plan, build, review and ship work in fixed stages with saved plans.
-
Get writing-planswriting-plans
For developers who give Claude a spec and want a test-first build plan before any code is written.
-
Get Khazix SkillsKhazix Skills
For Chinese-speaking users who want goal briefs for long agent runs, plus cleanup and research helpers.
-
Get i-have-adhdi-have-adhd
For readers with ADHD, or anyone, who want each reply to open with the next action and keep track of the steps.
planning-with-files
Get planning-with-files