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

66%

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 ./skills/planning-with-files/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

52%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 highly actionable, with copy-paste shell/PowerShell commands, shipped scripts, and a well-sequenced core workflow that includes validation and error-recovery loops. It is dragged down by severe verbosity — inline changelog narration, issue-number backstory, and version-gated behavior descriptions — and by progressive-disclosure failures where inlined detail and missing bundle files (templates, reference.md, examples.md) break the reference structure. The core planning guidance is strong but buried in roughly double the necessary text.

Suggestions

Move version histories (v2.x/v3.x notes), issue/PR backstory, host-capability tier tables, and attestation internals into a separate CHANGELOG.md or docs/ file, keeping SKILL.md to current-install instructions only.

Ship or remove the dead references: templates/task_plan.md, templates/findings.md, templates/progress.md, templates/loop.md, reference.md, examples.md, and plan-inventory.md are referenced but absent from the bundle.

Consolidate the four interleaved workflows (recovery, creation, turn-loop integration, autonomous/gated) into clearly separated sections with a single entry-point decision table, and replace version-conditioned prose ('since v3.18.3', 'v2.42.0 clarification') with a description of current behavior only.

DimensionReasoningScore

Conciseness

The ~500-line body interleaves changelog-style narration and design rationale ('v3.10.0', 'issue #237', 'PR #180 lesson', 'This is the lesson from issue #178: an incomplete plan is a normal state… accidental blocking infuriates users', host-tier tables, SHA-cache locations), which is padded material Claude does not need to execute the skill. Per the rubric, inline version/date-sensitive content outside a deprecated section penalizes conciseness; the file could be cut by more than half without losing executable instruction.

2 / 5

Actionability

Concrete copy-paste commands appear throughout ('sh "$PWF_SKILL_DIR/scripts/init-session.sh"', 'check-complete.sh --validate path/to/task_plan.md', PowerShell equivalents, 'set-active-plan.sh --list', the numbered manual /plan-goal and /plan-loop procedures, and the export PLAN_ID parallel workflow), and all nine referenced scripts exist in the bundle. It misses fully-executable status because 'Copy these templates to start' points at templates/*.md files that are not shipped, and reference.md, examples.md, and plan-inventory.md are dead references in this bundle.

4 / 5

Workflow Clarity

The core sequence (restore state → init → validate before substantive work → 2-Action Rule → update after each phase → 3-Strike error protocol → continue after completion) is clear, with explicit validation via check-complete.sh and plan-doctor.sh and a real error-recovery feedback loop in the 3-Strike protocol. It falls short of the top anchor because four interleaved workflows (recovery, creation, turn-loop integration, autonomous/gated modes) and version-conditioned behavior ('since v3.18.3', 'v2.42.0 clarification') make it hard to know which instructions apply to the current install.

4 / 5

Progressive Disclosure

Scored against the actual bundle: only scripts/ ships, yet the body inlines content that clearly belongs in separate files — version histories, attestation internals, host-capability tiers, and the full v2/v3 hardening narrative — while the 'Advanced Topics' pointers to reference.md and examples.md, the templates/ links, and plan-inventory.md reference files that do not exist in this bundle. This matches the inlined-content/dead-references anchor rather than the some-structure anchor, since the primary reference targets are missing entirely.

2 / 5

Total

12

/

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 distinctive, clearly stating what the skill does and giving an explicit 'Use for' clause, with named files and concrete hook/catchup behaviors. Its weaknesses are a trigger clause narrower than the skill's actual use cases and heavy space spent on security caveats that displaces natural trigger vocabulary. It performs solidly above the midpoint but not at the top anchors.

Suggestions

Expand the 'Use when' clause to mirror the body's trigger list (multi-step tasks, building/creating projects, tasks spanning many tool calls, resuming interrupted work) so users' natural phrasings match.

Trim the security/boundary sentences ('no network upload path', 'never runs commands declared in Markdown') to a single short clause and use the reclaimed space for the core capabilities (create plan, track phases, validate completion).

Add common synonyms such as 'long-running tasks', 'stay organized', or 'track progress' to improve trigger-term coverage.

DimensionReasoningScore

Specificity

Names several concrete actions and artifacts ('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'), matching the several-specific-actions anchor. It falls short of comprehensive because a large share of the text is security posture ('The skill has no network upload path', 'never runs commands declared in Markdown') rather than the skill's functional capabilities.

4 / 5

Completeness

Both what ('Persistent file-based planning… Keeps… on disk; lifecycle hooks inject… context') and when ('Use for research or work needing 5+ tool calls') are explicitly stated, so above the clear-what-only anchor. It is not a 5 because the 'when' is one thin closing clause without the multiple concrete trigger phrases of the top anchor.

4 / 5

Trigger Term Quality

Relevant keywords exist ('planning', 'multi-step', 'research', 'work needing 5+ tool calls') but common natural phrasings users would say — 'track progress', 'long-running task', 'stay organized', 'resuming work' — are missing, matching the some-keywords-but-missing-synonyms anchor. The single 'Use for' clause is also narrower than the body's own 'Multi-step tasks (3+ steps)' trigger list.

3 / 5

Distinctiveness Conflict Risk

'Persistent file-based planning' with named artifacts (task_plan.md, findings.md, progress.md, PLAN_ID) carves a mostly distinct niche with minor overlap risk against other planning/todo-style skills. Not fully conflict-free since generic 'planning for multi-step AI-agent work' could still collide with similar task-management skills.

4 / 5

Total

15

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (535 lines); consider splitting into references/ and linking

Warning

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 6 missing

Warning

Total

13

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

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.