planning-with-files

Overview of planning-with-files skill

What planning-with-files actually does

The planning-with-files skill gives an AI agent a simple, persistent planning system built on markdown files instead of ephemeral chat memory. Its core pattern is a 3-file workflow: task_plan.md for phases and status, notes.md for research and findings, and a final deliverable file such as output.md. If you want repeatable progress tracking across a multi-step task, this is the real reason to install planning-with-files.

Who should use planning-with-files

planning-with-files is best for people doing work that unfolds over multiple steps or sessions: research, migrations, audits, analysis, content planning, and general project organization. It is especially useful when you need the agent to remember what it already learned without re-pasting everything into context.

Best-fit job to be done

Use the planning-with-files skill when your real need is not “write one answer,” but “keep a running plan, collect evidence, and produce an output without losing the thread.” That makes planning-with-files for Project Management a good fit for lightweight execution tracking, but not for heavyweight PM frameworks.

Key differentiator versus a normal prompt

A normal prompt can ask for a plan. planning-with-files changes the working method. It pushes the agent to externalize plan, notes, and output into files that can survive context resets and long tool-using sessions. That matters more than the wording of any single prompt.

Where it is not the right fit

Skip planning-with-files for tiny one-shot questions, purely conversational brainstorming, or PRD-specific workflows. The repository explicitly points PRD work to prd-planner instead. If you do not want file creation in your workspace, this skill will feel heavier than a generic prompt.

How to Use planning-with-files skill

planning-with-files install context

The repository does not expose a dedicated install command inside SKILL.md, so users typically add it from the skill collection repo:

npx skills add https://github.com/zhaono1/agent-playbook --skill planning-with-files

This skill expects an environment where the agent can create and update markdown files. The declared tool assumptions include Read, Write, Edit, Bash, Grep, and Glob.

Files the skill expects to create

The practical default pattern is:

• task_plan.md — goals, phases, status, next steps
• notes.md — research, findings, decisions, references
• [deliverable].md — final artifact such as output.md

If you adopt planning-with-files usage in an existing repo, keep those names unless you have a reason to align with a local convention. Consistent filenames reduce agent confusion.

What to read first before adopting it

Read these in order:

1. skills/planning-with-files/SKILL.md
2. skills/planning-with-files/README.md

SKILL.md gives the operating model. README.md is shorter and useful for fast fit-checking. There are no extra rules, resources, or helper scripts here, so most of the value is in understanding the workflow pattern rather than discovering hidden automation.

How users actually invoke planning-with-files

In practice, people trigger the skill with requests like:

• “Plan a multi-step migration and track progress in files.”
• “Create a research plan and save notes and deliverables.”
• “Organize this project with persistent task files.”

Those examples work because they imply a task with multiple phases, not a single response.

Turn a rough goal into a strong prompt

Weak prompt:

• “Help me migrate this app.”

Better prompt for planning-with-files:

• “Use planning-with-files to create task_plan.md, notes.md, and migration-output.md for a React to Next.js migration. Break the work into phases, track open risks, save findings in notes.md, and keep task_plan.md updated as you go.”

Why this is better:

• names the file-based workflow
• gives a concrete deliverable
• signals that notes should persist
• asks for plan updates, not just an initial outline

Inputs that materially improve output quality

Provide these up front if you can:

• the goal
• constraints
• current repo or source material
• deadline or priority order
• preferred deliverable filename
• what “done” means

Example:

• Goal: audit onboarding flow and suggest fixes
• Constraints: no code changes, only analysis
• Inputs: /docs, /src/onboarding, analytics summary
• Deliverable: onboarding-audit.md
• Done means: findings, ranked issues, recommended actions

Without these, the agent can still create files, but the plan may stay generic.

Suggested workflow loop

A high-quality planning-with-files guide usually follows this sequence:

1. Create task_plan.md with objective and phases.
2. Research or inspect source material.
3. Save findings to notes.md.
4. Update task_plan.md with progress, blockers, and next actions.
5. Draft the final deliverable from notes.md.
6. Mark remaining gaps before finalizing.

The important behavior is the loop, not just the initial file creation.

Good use cases for planning-with-files for Project Management

For planning-with-files for Project Management, think lightweight coordination, not enterprise PM tooling. Good examples:

• migration planning
• research tracking
• implementation checklists
• content production workflows
• technical audits
• dependency investigations

It works best when the agent is both discovering information and turning it into a finished output.

Common adoption blockers

The usual blockers are practical, not conceptual:

• users expect instant value on a tiny task
• they do not give the agent a clear deliverable
• they never ask the agent to keep updating task_plan.md
• they already have a strict project file structure and do not want new top-level files

If any of those apply, decide before installing whether you want this exact pattern or just a one-off planning prompt.

Practical file placement advice

The repo examples show simple root-level filenames. That is fine for isolated tasks. In a busy project, you may get cleaner results by placing them in a task folder such as /workstreams/migration/. If you do that, specify the paths explicitly in your prompt so the agent does not split files across locations.

planning-with-files skill FAQ

Is planning-with-files better than asking for a plan in chat?

For multi-step work, usually yes. The advantage is persistence and traceability. planning-with-files stores the evolving plan and findings in files, so the agent can resume with less drift. If you only need an outline once, a normal prompt is simpler.

Is the planning-with-files skill beginner-friendly?

Yes, because the pattern is simple: one plan file, one notes file, one output file. The main beginner mistake is using it for tasks too small to justify file overhead.

Does planning-with-files require a specific project type?

No. The pattern is intentionally generic. It can support engineering, research, operations, writing, or analysis tasks as long as the agent can read and write files.

When should I not use planning-with-files?

Do not use planning-with-files for:

• one-turn answers
• purely conversational ideation
• tasks where files cannot be written
• PRD-specific workflows better handled by prd-planner

How is it different from task trackers or TodoWrite?

The skill addresses a different problem: durable working memory. A task tracker can list todos, but planning-with-files keeps the plan, the evidence, and the final output connected in plain markdown files the agent can reopen and extend.

Does planning-with-files include automation or scripts?

Not in this repo path. The value is the workflow pattern itself, not bundled tooling. That makes it easy to understand, but also means output quality depends heavily on how clearly you define the task.

How to Improve planning-with-files skill

Start planning-with-files with a sharper task frame

The fastest way to improve planning-with-files results is to give a task frame with scope, constraints, and a named deliverable. “Research this” is weak. “Investigate auth failures, save findings in notes.md, and produce auth-failure-analysis.md with root causes and fixes” is much stronger.

Ask for file updates, not just file creation

A common failure mode is that the agent creates the three files once and then works mostly in chat. Tell it to update task_plan.md after each major step and to store substantive findings in notes.md. This keeps the workflow alive.

Make phases explicit for long tasks

If the task is complex, ask the agent to structure task_plan.md into phases such as discovery, analysis, execution, validation, and handoff. That gives the skill more traction than an undifferentiated checklist.

Improve notes quality with evidence expectations

notes.md becomes much more useful when you ask for:

• source paths or references
• assumptions
• open questions
• decisions made
• rejected options

That turns notes from a scratchpad into reusable working memory.

Reduce generic outputs with a deliverable spec

If your final file should be a decision memo, migration checklist, audit report, or implementation plan, say so. The planning-with-files skill is only as specific as the target output you define.

Recover after a weak first pass

If the first run is shallow, do not restart from zero. Ask the agent to:

1. review task_plan.md for missing phases
2. enrich notes.md with evidence and unresolved questions
3. rewrite the deliverable using the updated notes

This usually improves quality faster than re-prompting from scratch.

Adapt the file pattern to your workspace deliberately

The default 3-file pattern is useful because it is minimal. Keep it unless your team already has a structure worth matching. If you rename files or move them into subfolders, specify the exact paths so planning-with-files usage stays consistent across sessions.

Pair planning-with-files with source inspection

The skill gets stronger when the agent has real materials to inspect: repo folders, docs, logs, issue lists, or requirements. If you provide only an abstract goal, the workflow still runs, but the resulting files may read like placeholders rather than grounded work.

Watch for the main misfit signal

The clearest signal that planning-with-files is the wrong tool is when the plan files become bureaucracy instead of support. If the task can be solved well in one focused response, skip the overhead and use a direct prompt instead.