planning-with-files

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.cursor/skills/planning-with-files/SKILL.md

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body delivers a clear, actionable planning workflow with concrete commands, well-organized sections, and a strong error-recovery protocol. It loses points for redundant conceptual sections and, more importantly, for referencing template and reference files that do not exist in the actual bundle.

Suggestions

Ship the referenced files (templates/task_plan.md, findings.md, progress.md, reference.md, examples.md) or remove/inline the links so no navigation path dangles.

Collapse the redundant discipline sections (File Purposes 'When to Update', Read vs Write Decision Matrix, 5-Question Reboot Test) into one table, and drop the Manus/RAM-disk metaphor.

Integrate `scripts/check-complete.sh` into the Quick Start as an explicit final validation step ('verify all phases complete before reporting done').

Dimension	Reasoning	Score
Conciseness	The body is table-dense and mostly efficient, but includes unnecessary explanation Claude does not need ('Work like Manus', the 'Context Window = RAM / Filesystem = Disk' metaphor) and redundant sections — File Purposes, Read vs Write Decision Matrix, and the 5-Question Reboot Test restate the same read/write discipline three ways. This fits anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') rather than 4, whose over-explanation would be only minor instances.	3 / 5
Actionability	Concrete executable commands are given for the common cases: the session-catchup bash/PowerShell invocations, `scripts/init-session.sh "Task Name"`, `git diff --stat`, and the `set-active-plan.sh --list` listing command. Not 5 because the bash example hardcodes the `.cursor/skills/...` install path and the list-plans section leaves `<skill-dir>` as an unresolved placeholder, so guidance is mostly but not fully copy-paste ready.	4 / 5
Workflow Clarity	The restore-state step followed by the four numbered Quick Start steps gives a clear sequence, and the 3-Strike Error Protocol provides an explicit diagnose/alternative/rethink/escalate feedback loop with an escalation checkpoint. Not 5 because the validation script (`check-complete.sh` — 'Verify all phases complete') is listed under Scripts but never wired into the workflow as a checkpoint instruction, leaving a minor validation gap.	4 / 5
Progressive Disclosure	Section structure is good and references are clearly signaled one level deep (Templates, Scripts, Advanced Topics), but scored against the actual bundle: `templates/task_plan.md`, `reference.md`, and `examples.md` are referenced yet absent, so three of the documented navigation targets dangle. Only the `scripts/` references resolve, which pulls this below anchor 4 to 'references present but' defective organization.	3 / 5
	Total	14 / 20 Passed

Description

67%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific and third-person, with a clear what and an explicit when-to-use clause, and it honestly bounds its own behavior (no network upload path, aggregate counts only). Its main weaknesses are a narrow, partly unnatural trigger clause ('5+ tool calls') and missing common trigger synonyms for planning and progress tracking.

Suggestions

Broaden the trigger clause to natural user phrasing, e.g. 'Use for multi-step tasks, research, project work, or when resuming interrupted work' rather than only 'research or work needing 5+ tool calls'.

Add the core workflow actions (phase tracking, findings logging, error tracking with escalation) so the 'what' covers what the skill actually does day-to-day, not just its file/hook plumbing.

Trim the security/disclaimer detail ('no network upload path', nonce framing) that consumes trigger-term budget without helping a user decide when to invoke the skill.

Dimension	Reasoning	Score
Specificity	Names concrete actions and artifacts ('Keeps task_plan.md, findings.md, and progress.md on disk', 'lifecycle hooks inject selected project planning context', 'emits aggregate counts only'), matching the 'several specific actions; minor gaps' anchor. It is not 5 because core workflow capabilities (phase tracking, error logging, templates) are never mentioned; not 3 because far more than 1-2 concrete actions are listed.	4 / 5
Completeness	Both are present: a clear 'what' (persistent file-based planning with named files and hook/recovery behavior) and an explicit 'when' clause ('Use for research or work needing 5+ tool calls'). Not 5 because the 'when' is narrow — it omits multi-step builds, project organization, and resuming interrupted work that the skill body itself targets, so it 'could be more explicit or specific'.	4 / 5
Trigger Term Quality	Relevant keywords exist ('planning', 'multi-step AI-agent work', 'research') but common natural variations are missing, and the trigger 'work needing 5+ tool calls' is not phrasing a user would naturally say. It fits anchor 3 ('some relevant keywords but missing common variations') better than anchor 4, which expects good coverage of terms users actually utter like 'plan this', 'track progress', or 'stay organized'.	3 / 5
Distinctiveness Conflict Risk	Specific file names, lifecycle hooks, and session-catchup mechanics carve out a distinct niche with minimal conflict risk ('Persistent file-based planning', 'task_plan.md, findings.md, and progress.md'). Not 5 because 'planning' is a broad domain with minor overlap risk against generic todo/task-management skills.	4 / 5
	Total	15 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 5 missing	Warning

	Total	14 / 16 Passed

Repository: OthmanAdi/planning-with-files
Path: .cursor/skills/planning-with-files/SKILL.md
Commit: dab9d16

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.