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

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

77%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 skill body is a well-engineered process guide: highly actionable commands, an explicit plan-format contract, strong validation gates, and a clear error-escalation protocol. Its weaknesses are modest redundancy in file-placement guidance and a reference layer whose links do not resolve against the shipped bundle.

Suggestions

Fix the broken reference paths: either ship the templates/ directory the three template links point to, or update the links to the actual locations, and change '[reference.md](reference.md)' / '[examples.md](examples.md)' to 'references/reference.md' and 'references/examples.md' so they match the plan-inventory link's convention.

Consolidate the thrice-repeated file-placement guidance ('Where Files Go' table, the Note callout, and the 'Create files in skill directory' anti-pattern row) into a single section to save tokens.

Simplify the opening 'Restore Project State' section so the resolve-plan-dir step, the session-catchup snippets, and the creation contract appear in one linear order, reducing the interleaving that currently requires re-reading.

DimensionReasoningScore

Conciseness

The body is dense with actionable rules, tables, and commands rather than explanations of concepts Claude already knows, but there is minor repetition: file-placement guidance appears in 'Where Files Go', the 'Note' callout, and the Anti-Patterns table, and 'Quick Start' overlaps the 'New plan creation contract'. This matches 'efficient with minor instances that could be trimmed' rather than the every-token-earns-its-place level of score 5.

4 / 5

Actionability

Concrete, runnable guidance dominates: copy-paste bash and PowerShell snippets for session-catchup.py, init-session.sh, check-complete.sh --validate, and set-active-plan.sh --list/--archive, plus an explicit format contract ('### Phase N: Name with exactly one **Status:** pending/in_progress/complete line'). Minor gaps — the '<skill-dir>' placeholder substitution and an opening that interleaves restore, catchup, and resolve instructions — keep it below the fully copy-paste-ready bar of score 5.

4 / 5

Workflow Clarity

The multi-step lifecycle is clearly sequenced (restore/resolve plan dir, read planning files, init new plan, validate, execute phases, update after each phase, escalate after 3 failures) with explicit validation checkpoints ('Validation must succeed before substantive work and after changing phase structure'), a feedback loop in the 3-Strike Error Protocol, and a preview/confirm safety step for the destructive archive operation ('--archive previews the move... --yes applies it'). This matches the score-5 anchor: clear sequence, explicit validation, error-recovery loops, and checklists.

5 / 5

Progressive Disclosure

The body is a genuine overview with well-signaled, one-level-deep references (Templates, Scripts, Advanced Topics, plan-inventory) and appropriately outsourced detail. However, scored against the actual bundle: the three templates/task_*.md links point to a nonexistent templates/ directory, and the reference.md and examples.md links point to the skill root while the files actually live in references/ — only references/plan-inventory.md resolves as written. These are more than the 'minor organization gaps' of score 4's ceiling but the structure itself is better than the poorly-signaled case of score 3, placing it between anchors; the broken paths and inconsistent reference locations pull it to the middle.

4 / 5

Total

17

/

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 about artifacts and behaviors, clearly answers both what and when, and carves out a recognizable niche. Its main weaknesses are a narrow trigger clause that misses the natural phrases users would actually say, and capability space spent on security caveats instead of the core planning workflow.

Suggestions

Broaden the 'Use for...' clause with concrete trigger phrases users naturally say, e.g. 'long-running tasks, multi-step projects, breaking work into phases, or resuming where a previous session left off', instead of the single 'research or work needing 5+ tool calls' condition.

Replace part of the privacy-caveat detail ('no network upload path', 'never runs commands declared in Markdown') with a brief enumeration of the core workflow actions — creating a phased plan, logging findings, tracking progress, and validating phase completion — so the capability coverage matches the score-5 specificity anchor.

DimensionReasoningScore

Specificity

The description lists several concrete actions and artifacts — 'Keeps task_plan.md, findings.md, and progress.md on disk', 'lifecycle hooks inject selected project planning context', and the session-catchup.py --metadata/--replay behavior — but never enumerates the core planning workflow actions (create plan, track phases, validate), and a large share of the text is privacy/security caveat rather than capability. It sits above score 3 (which requires only 1-2 concrete actions) but below 5 due to the coverage gaps.

4 / 5

Completeness

Both what and when are explicitly present: 'Persistent file-based planning... Keeps task_plan.md, findings.md, and progress.md on disk' answers what, and 'Use for research or work needing 5+ tool calls' answers when. The when-clause is explicit but narrow — a single trigger condition rather than the concrete multi-phrase trigger set of the score-5 anchor, while clearly stronger than a merely implied 'when' at score 3.

4 / 5

Trigger Term Quality

Relevant keywords like 'planning', 'multi-step', 'research', and '5+ tool calls' are present, but common natural phrases a user would say — 'long task', 'break this down', 'track progress', 'stay organized', 'todo' — are missing. Coverage is neither the sparse one-or-two-generic-keyword case (2) nor the good-coverage-with-few-missing case (4).

3 / 5

Distinctiveness Conflict Risk

Named planning files (task_plan.md, findings.md, progress.md) and the session-catchup.py script give it a distinct identity, but the broad terms 'planning' and 'research' create minor overlap risk with general todo/task-tracking and research-organization skills. Mostly distinct with minor overlap, matching score 4 rather than the minimal-conflict niche of score 5.

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: 5 missing

Warning

Total

14

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

.codebuddy/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.