CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

60%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 well-sequenced, actionable planning workflow with real validation checkpoints and error-recovery protocol, and the scripts it cites all exist in the bundle. Its two real problems are redundancy in the file-location guidance and a reference layer that mostly points at files absent from the bundle, which breaks both template usage and the advanced-topics navigation.

Suggestions

Ship the referenced files (templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, plan-inventory.md) or remove/inline the dead links — every non-script reference in the body currently resolves to nothing.

Add a copy-paste example command for the restore entry point (resolve-plan-dir.sh with PLAN_ID and PWF_PLAN_ROOT) so the first step of the workflow is as executable as the later ones.

State the project-root file-location rule once (the table) and drop the duplicate note and anti-patterns row; the RAM/disk metaphor section can also be cut since it explains what Claude already knows.

DimensionReasoningScore

Conciseness

The body is largely table-dense and imperative, but 'planning files go in your project directory' is repeated three times (location table, the note after Quick Start, and the anti-patterns row), and the 'Context Window = RAM / Filesystem = Disk' section explains a concept Claude already knows — fitting the 'mostly efficient but some unnecessary explanation' anchor rather than the merely-trimmable anchor 4.

3 / 5

Actionability

Provides concrete, runnable invocations for session-catchup.py --metadata (bash and PowerShell), init-session.sh, check-complete.sh --validate, and set-active-plan --list/--archive, but the primary restore entry point ('Use the installed scripts/resolve-plan-dir.sh (or .ps1) with the host's PLAN_ID and PWF_PLAN_ROOT') is described without an example command line, matching the 'mostly executable guidance with minor gaps' anchor.

4 / 5

Workflow Clarity

The lifecycle has explicit validation checkpoints ('Validation must succeed before substantive work and after changing phase structure'), a 3-strike escalation feedback loop, and an approval gate for archiving, but the opening restore section interleaves resolve-plan-dir prose with a session-catchup snippet whose role in the sequence is unclear, leaving minor gaps versus the fully explicit anchor 5.

4 / 5

Progressive Disclosure

References are clearly signaled and one level deep, but scored against the actual bundle, six referenced paths are dead: templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, and plan-inventory.md do not exist in the bundle, so 'Copy these templates to start' and 'See [reference.md](reference.md)' fail at use time — broken navigation for over half the non-script references places this below the 'references present but not clearly signaled' anchor 3.

2 / 5

Total

13

/

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 concrete, third-person, and answers both what and when, with clearly named artifacts and behaviors. Its main weaknesses are a mechanical, narrow trigger clause ('5+ tool calls') and heavy investment in implementation detail that crowds out the natural phrases users would actually say when reaching for a planning skill.

Suggestions

Broaden the 'Use when...' clause with natural user phrasing, e.g. 'Use for multi-step tasks, long-running research, or project work where tracking phases, findings, and progress across sessions matters.'

Add common trigger synonyms (planning, task tracking, progress tracking, staying organized, resuming work) so the skill surfaces for the vocabulary users actually use rather than only 'research' or a tool-call count.

Trim implementation detail (nonce framing, gated-mode internals) in favor of one or two capability-oriented actions such as phase tracking with validation and error-logging protocol.

DimensionReasoningScore

Specificity

Names several concrete actions ('Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context', 'session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only'), but coverage is skewed toward recovery and hook mechanics rather than the breadth of planning capabilities, matching the 'several specific actions; minor gaps' anchor rather than the comprehensive anchor 5.

4 / 5

Completeness

Both what (persistent file-based planning with named files, hooks, and recovery modes) and when ('Use for research or work needing 5+ tool calls') are explicitly present, but the when-clause is narrow and metric-driven rather than covering the multi-step/build/organize cases the body targets, matching anchor 4 rather than the concrete-trigger-phrases anchor 5.

4 / 5

Trigger Term Quality

'planning', 'multi-step', and 'research' are natural terms, but the only trigger phrase is 'Use for research or work needing 5+ tool calls', which is mechanical rather than something a user would say, and common variations like 'long task', 'track progress', or 'stay organized' are absent — fitting the 'some relevant keywords but missing common variations' anchor.

3 / 5

Distinctiveness Conflict Risk

Named planning files, hook-based context injection, and the recovery/catchup behavior carve a distinct niche with little chance of firing for unrelated skills; only minor overlap remains with generic task-organization skills, fitting the 'mostly distinct; minor overlap risk' anchor.

4 / 5

Total

15

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

relative_links

Relative link issues: 6 missing

Warning

Total

14

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

.cursor/skills/planning-with-files/SKILL.md

Reviewed

Table of Contents

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.