planning-with-files
Implements file-based planning for complex multi-step tasks. Creates taskplan.md, findings.md, and progress.md as persistent working memory. Use when starting tasks requiring 5 tool calls, multi-phase projects, research, or any work where losing track of goals and progress would be costly.
- Installs
- 133
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/trailofbits/skills-curated --skill planning-with-files- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads planning-with-files automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Planning with Files
Use persistent markdown files as working memory on disk.
Quick Start
- Create planning files -- use
/planor create manually from templates - Create
task_plan.mdwith goal, phases, and key questions - Create
findings.mdfor research and decisions - Create
progress.mdfor session logging - Re-read the plan before decisions -- refreshes goals in attention
- Update after each phase -- mark status, log errors
When to Use
- Multi-step tasks (3+ phases)
- Research projects requiring many searches
- Building or creating projects with multiple files
- Tasks spanning many tool calls (>10)
- Any work where losing track of goals would be costly
- Tasks that may span multiple sessions
When NOT to Use
- Simple questions or quick lookups
- Single-file edits with obvious scope
- Tasks completable in under 5 tool calls
- Conversational exchanges without implementation
Core Pattern
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
Anything important gets written to disk.
After many tool calls, the original goal drifts out of the attention
window. Reading task_plan.md brings it back. This is the single
most important pattern in file-based planning.
File Purposes
| File | Purpose | When to Update |
|---|---|---|
task_plan.md | Phases, progress, decisions | After each phase completes |
findings.md | Research, discoveries, decisions | After ANY discovery |
progress.md | Session log, test results | Throughout the session |
All three files go in the project root, not the plugin directory.
Critical Rules
1. Create Plan First
Never start a complex task without task_plan.md. This is
non-negotiable. The plan is your persistent memory.
2. The 2-Action Rule
After every 2 search, browse, or read operations, immediately save
key findings to findings.md. Multimodal content (images, browser
results, PDF contents) does not persist in context -- capture it as
text before it is lost.
3. Read Before Decide
Before any major decision, re-read task_plan.md. This pushes
goals and context back into the recent attention window, counteracting
the "lost in the middle" effect that occurs after ~50 tool calls.
[Original goal -- far away in context, forgotten]
...many tool calls...
[Recently read task_plan.md -- gets ATTENTION]
→ Now make the decision with goals fresh in context
4. Update After Act
After completing any phase:
- Mark phase status:
in_progress->complete - Log any errors encountered in the Errors table
- Note files created or modified in
progress.md
5. Log ALL Errors
Every error goes in task_plan.md. Include the attempt number and
resolution. This builds knowledge and prevents repeating failures.
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
6. Never Repeat Failures
If an action failed, the next action must be different. Track what you tried and mutate the approach.
if action_failed:
next_action != same_action
3-Strike Error Protocol
ATTEMPT 1: Diagnose & Fix
-> Read error carefully
-> Identify root cause
-> Apply targeted fix
ATTEMPT 2: Alternative Approach
-> Same error? Try a different method
-> Different tool? Different library?
-> NEVER repeat the exact same failing action
ATTEMPT 3: Broader Rethink
-> Question assumptions
-> Search for solutions
-> Consider updating the plan
AFTER 3 FAILURES: Escalate to User
-> Explain what you tried (with attempt log)
-> Share the specific error
-> Ask for guidance
Read vs Write Decision Matrix
| Situation | Action | Reason |
|---|---|---|
| Just wrote a file | Don't read it | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal content doesn't persist |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context is stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover full state |
5-Question Reboot Test
If you can answer these from your planning files, context is solid:
| Question | Answer Source |
|---|---|
| Where am I? | Current phase in task_plan.md |
| Where am I going? | Remaining phases |
| What's the goal? | Goal statement in plan |
| What have I learned? | findings.md |
| What have I done? | progress.md |
Anti-Patterns
| Don't | Do Instead |
|---|---|
| State goals once and forget | Re-read plan before decisions |
| Hide errors and retry silently | Log every error to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |
| Repeat failed actions | Track attempts, mutate approach |
| Create files in plugin directory | Create files in project root |
References
- Templates -- starter templates for all three planning files
- Principles -- context engineering principles behind this approach
- Examples -- concrete examples and error recovery patterns
FAQ
What does the planning-with-files skill do?
Implements file-based planning for complex multi-step tasks. Creates taskplan.md, findings.md, and progress.md as persistent working memory. Use when starting tasks requiring 5 tool calls, multi-phase projects, research, or any work where losing track of goals and progress would be costly.
How do I install planning-with-files?
Run npx skills add https://github.com/trailofbits/skills-curated --skill planning-with-files in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/planning-with-files/ (personal) or .claude/skills/planning-with-files/ (project).
Which AI agents can use planning-with-files?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is planning-with-files safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains planning-with-files?
It is published by trailofbits in trailofbits/skills-curated. It has 133 recorded installs.
More from trailofbits/skills-curated
ghidra-headless
trailofbits/skills-curated
Reverse engineers binaries using Ghidra's headless analyzer. Use when decompiling executables, extracting functions, strings, symbols, or analyzing call graphs from compiled binaries without the Ghidra GUI.
humanizer
trailofbits/skills-curated
Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases. 30c5c8d (Update humanizer plugin to upstream v2.2.0)
skill-extractor
trailofbits/skills-curated
Extracts reusable skills from work sessions. Use when: (1) a non-obvious problem was solved worth preserving, (2) a pattern was discovered that would help future sessions, (3) a workaround or debugging technique needs documentation. Manual invocation only via /skill-extractor command - no automatic triggers or hooks.
openai-develop-web-game
trailofbits/skills-curated
Use when the agent is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with rendergametotext. Originally from OpenAI's curated skills catalog.
security-awareness
trailofbits/skills-curated
Teaches agents to recognize and avoid security threats during normal activity. Covers phishing detection, credential protection, domain verification, and social engineering defense. Use when building or operating agents that access email, credential vaults, web browsers, or sensitive data.
wooyun-legacy
trailofbits/skills-curated
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.