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

72%

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

Quality

Content

62%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's operational core is excellent — concrete commands, explicit validation gates, and a strong error-recovery protocol — but it is buried in a very long body full of version history, issue-number archaeology, and triplicated guidance. Progressive disclosure is undermined by referenced files (templates, reference.md, examples.md, plan-inventory.md) that are not present in the bundle and by deep operational detail that belongs in separate reference docs.

Suggestions

Strip version numbers, dates, and issue/PR references from the main body (or collect them in a dedicated changelog/deprecated section); they are time-sensitive noise that penalizes every read.

Move the Claude Code turn-loop integration, install-scope tables, host-tier matrices, and v3 hardening detail into the referenced reference docs so SKILL.md stays a lean overview.

Ship the missing referenced files (templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, plan-inventory.md) or remove/inline the links — the core "copy these templates" action currently fails.

State the parallel-task pinning rule once and reference it; it currently appears in at least three places.

DimensionReasoningScore

Conciseness

The ~485-line body is saturated with version numbers (v2.36.1, v2.37.0, v3.24.0), dates ("May 2026"), issue references (#237, #178, PR #180), and developer changelog narrative (e.g., the "Shared parent directories (v3.9.0)" history and the "lesson from issue #178" prose), and the parallel-task pinning instructions are repeated nearly verbatim three times. This matches "noticeably verbose; several unnecessary explanations or padded sections"; the lean core pattern (file purposes, rules, matrices) does not lift it to 3 because the padding is pervasive rather than occasional.

2 / 5

Actionability

The body gives copy-paste-ready commands for every mechanism — `sh "$PWF_SKILL_DIR/scripts/init-session.sh"`, `check-complete.sh --validate path/to/task_plan.md`, `session-catchup.py --metadata "$(pwd)"`, resolver calls with `--check-ambiguity`, PowerShell equivalents, and a 6-step manual `/plan-goal` procedure — landing at "mostly executable guidance with minor gaps". It is not anchor 5 because the templates the model is told to copy (`templates/task_plan.md` etc.) are absent from the bundle, and a few steps remain abstract ("Compose a goal condition", "Confirm to the user").

4 / 5

Workflow Clarity

The core workflow is explicitly sequenced with validation checkpoints and error feedback loops: restore/pin the plan first, init before implementation, "Validation must succeed before substantive work and after changing phase structure", update after each phase, plus the 3-Strike error protocol with escalation and the Read/Write decision matrix and 5-Question reboot checklist. This matches the anchor-5 pattern of clear sequence, explicit validation steps, feedback loops, and checklists; the surrounding sprawl is a conciseness/organization problem, not a sequencing gap.

5 / 5

Progressive Disclosure

Section headers are clear and the Advanced Topics links are well signaled one level deep, but scored against the actual bundle: `templates/task_plan.md`, `reference.md`, `examples.md`, and `plan-inventory.md` are referenced yet absent (only `scripts/` ships), and ~150 lines of install-scope tables, host-tier matrices, and v3 hardening detail are inlined that clearly belong in separate reference files. This fits "some structure but could be better organized; content that should be separate is inline"; it stays above 2 because navigation and signaling within SKILL.md itself are genuinely good.

3 / 5

Total

14

/

20

Passed

Description

72%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 highly concrete and answers both what and when explicitly, with a clear niche in persistent file-based planning. Its weaknesses are trigger phrasing — heavy on implementation jargon and security-policy detail, light on the natural terms users would actually say — and a when-clause whose "5+ tool calls" threshold narrows and conflicts with the body's stated triggers. Trimming the policy clauses in favor of natural trigger synonyms would raise trigger quality and distinctiveness.

Suggestions

Add natural trigger phrases users would actually say (e.g., "task tracking", "long-running task", "keep progress across sessions") and drop jargon like "nonce-framed excerpts" that no user would utter when invoking the skill.

Align the when-clause with the body's stated triggers ("3+ steps", "building projects") instead of the machine-oriented "5+ tool calls" threshold.

Move the security-policy statements ("no network upload path", "never runs commands declared in Markdown") into the body's Security Boundary section so the description focuses on capabilities and triggers.

DimensionReasoningScore

Specificity

Nearly every clause names a concrete action or artifact: "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", "Optional gated mode can request continuation only when the host supports it". There is no vague or generic language, matching the comprehensive-concrete-actions anchor; the unmentioned parallel-plan/attestation features are minor relative to the concrete coverage stated.

5 / 5

Completeness

Both what ("Persistent file-based planning… Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject…") and when ("Use for research or work needing 5+ tool calls") are explicitly present. The when-clause is concrete but narrow and inconsistent with the body's "Multi-step tasks (3+ steps)" trigger, so it falls at "both present; when could be more explicit or specific" rather than the fully-concrete-trigger-phrases anchor 5.

4 / 5

Trigger Term Quality

Some relevant natural keywords appear ("planning", "multi-step", "research", "5+ tool calls"), but common user phrasings like "task tracking", "keep progress", "todo", or "long-running task" are missing, and much of the description is implementation jargon ("nonce-framed excerpts", "session-catchup.py") a user would never say. This fits the "some relevant keywords but missing common variations or synonyms" anchor rather than 4, where keyword coverage would be genuinely good.

3 / 5

Distinctiveness Conflict Risk

The niche is clear and distinctive (persistent planning files plus lifecycle hooks, with named artifacts), but the trigger "Use for research or work needing 5+ tool calls" is broad enough to overlap with many complex-task and research-orchestration skills, so it is "mostly distinct; minor overlap risk" rather than the minimal-conflict anchor 5.

4 / 5

Total

16

/

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 (518 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

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