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

71%

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

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 well-structured, largely executable planning workflow with real validation checkpoints and an explicit error-recovery protocol. Its main weaknesses are redundant re-explanatory sections, a missing example invocation for the entry-point plan-resolution script, and four bundle references (all three templates plus plan-inventory.md) that point to files not present.

Suggestions

Ship the referenced templates/ directory (task_plan.md, findings.md, progress.md) and plan-inventory.md in the bundle, or remove/fix those links — four referenced paths currently resolve to nothing.

Cut sections that restate known concepts or duplicate other sections: the Core Pattern RAM/disk analogy, the 5-Question Reboot Test (duplicates File Purposes), and the create-plan-first repetition across Quick Start, Critical Rules, and Anti-Patterns.

Add a copy-paste example of scripts/resolve-plan-dir.sh (with PLAN_ID and PWF_PLAN_ROOT) to the FIRST section so the entry-point step is as executable as the other command flows.

DimensionReasoningScore

Conciseness

Mostly efficient — tables, contracts, and command blocks are tight — but several sections explain concepts Claude already knows or repeat other sections: the "Context Window = RAM / Filesystem = Disk" analogy, the 5-Question Reboot Test (which restates the File Purposes table), and the create-plan-first rule appearing in Quick Start step 1, Critical Rule 1, and Anti-Patterns. Not 2 because there is no tutorial-style padding or library explanation; not 4 because the redundant and re-explanatory sections exceed minor instances.

3 / 5

Actionability

Mostly executable with copy-paste commands in both bash and PowerShell variants (session-catchup.py --metadata, init-session.sh, check-complete.sh --validate, set-active-plan.sh --list/--archive/--restore). Not 5 because the entry-point step has no example invocation — "Use the installed scripts/resolve-plan-dir.sh (or .ps1) with the host's PLAN_ID and PWF_PLAN_ROOT" describes usage without showing it — and a few directives remain abstract ("correct the pin", "report the issue for its owner to review").

4 / 5

Workflow Clarity

The sequence is clear with explicit checkpoints: restore-before-create ordering, "Validation must succeed before substantive work and after changing phase structure", the 3-Strike Error Protocol as an escalating feedback loop ending in user escalation, and archive gating ("--archive <id> previews the move... --yes applies it", "Never archive on age or completion alone"). Not 5 because the restore-first entry flow interleaves hook behavior, plan resolution, and session-catchup without showing the resolve-plan-dir invocation, leaving minor gaps in the most important sequence.

4 / 5

Progressive Disclosure

Structure and signaling are good — clearly labeled one-level references ("Manus Principles: See references/reference.md", "Real Examples: See references/examples.md") and a well-organized section layout — but scored against the actual bundle, four referenced paths are broken: templates/task_plan.md, templates/findings.md, templates/progress.md (no templates/ directory exists) and plan-inventory.md, and the templates are presented as operationally central ("Copy these templates to start"). Not 4 because broken links to the workflow's core templates exceed "minor organization gaps"; not 2 because content is well-sectioned with clearly signaled references rather than inlined or buried.

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 technically precise about mechanisms and security boundaries, with an explicit Use-for clause. Its weaknesses are thin natural trigger vocabulary (dominated by implementation jargon), a when-clause narrower than the skill's actual use cases, and capability coverage skewed toward defensive caveats rather than the planning workflow itself.

Suggestions

Add natural trigger synonyms users would actually say (e.g., "task tracking", "project plan", "long-running task", "stay organized") to the Use-for clause to improve trigger term coverage.

Broaden the when-clause to match the body's When-to-Use section (multi-step tasks, building/creating projects, tasks needing organization) instead of only "research or work needing 5+ tool calls".

Move implementation jargon ("nonce-framed excerpts", "gated mode", flag-level detail for session-catchup.py) into the skill body, freeing description space for the core planning capabilities (phase tracking, error logging, plan validation).

DimensionReasoningScore

Specificity

Names several concrete actions with specific artifacts — "Keeps task_plan.md, findings.md, and progress.md on disk", "lifecycle hooks inject selected project planning context", "reads same-project local agent session records and emits aggregate counts" — matching the several-specific-actions anchor. Not 5 because coverage tilts toward defensive scoping statements ("no network upload path", "never runs commands declared in Markdown") while omitting the core planning workflow capabilities the body documents (phase tracking, plan validation, archiving).

4 / 5

Completeness

Both parts are explicit: a clear what ("Persistent file-based planning... Keeps task_plan.md, findings.md, and progress.md on disk") and an explicit when ("Use for research or work needing 5+ tool calls"), so it is not capped at 3. Not 5 because the when-clause is narrower than the skill's stated applicability (the body lists multi-step tasks of 3+ steps and building projects) and "5+ tool calls" is not a phrase users naturally think in, falling short of concrete user-language trigger phrases.

4 / 5

Trigger Term Quality

Some relevant natural keywords exist ("planning", "multi-step", "research"), but they are sparse relative to implementation jargon ("lifecycle hooks", "nonce-framed excerpts", "gated mode", "session-catchup.py --metadata") and common user variations like "task tracking", "project plan", or "stay organized" are missing. Not 4 because good keyword coverage would include several natural phrasings users actually say, which this lacks.

3 / 5

Distinctiveness Conflict Risk

Mostly distinct: the named file trio (task_plan.md, findings.md, progress.md) and the hook-injection mechanism give it a clear identity distinct from generic file skills. Not 5 because planning/task-organization is a crowded skill category and the broad when-clause ("research or work needing 5+ tool calls") leaves minor overlap risk with other planning or task-management skills; not 3 because the specific artifacts and mechanism prevent real confusion.

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

Warning

Total

14

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

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