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

74%

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

Quality

Content

71%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.

A well-structured operational skill with concrete commands, explicit validation gates, and strong error-recovery guidance; its main weaknesses are a muddled, example-less entry-point step and a Templates section whose links are broken in the actual bundle. Most dimensions land at 4, with progressive disclosure pulled to 3 by the dead template paths.

Suggestions

Ship the templates directory in the bundle (or repoint the Templates section to files that exist), since `templates/task_plan.md`, `templates/findings.md`, and `templates/progress.md` are all dead links in the current bundle.

Add a concrete example invocation for `scripts/resolve-plan-dir.sh`/`.ps1` with `PLAN_ID` and `PWF_PLAN_ROOT` — it is the first commanded step but the only helper with no shown command.

Tighten the redundancy between 'The Core Pattern', 'File Purposes', and the '5-Question Reboot Test', which restate the same persistence philosophy three times.

DimensionReasoningScore

Conciseness

The body is dense and table-driven ('File Purposes', 'Read vs Write Decision Matrix', 'Anti-Patterns') with almost no explanation of concepts Claude already knows, though 'The Core Pattern' RAM/disk metaphor and the '5-Question Reboot Test' overlap enough with the File Purposes table that they could be trimmed. This sits at 'efficient; minor instances of over-explanation', not 5, because a few sections restate the same persistence philosophy three ways.

4 / 5

Actionability

Mostly executable guidance: copy-paste-ready invocations are given for `session-catchup.py --metadata` (bash and PowerShell), `init-session.sh`, `check-complete.sh --validate`, and `set-active-plan.sh --list`, plus exact format rules ('Keep each phase as `### Phase N: Name` with exactly one `**Status:**` line'). It falls short of 5 because the very first instructed action — 'Use the installed `scripts/resolve-plan-dir.sh` (or `.ps1`) with the host's `PLAN_ID` and `PWF_PLAN_ROOT`' — never shows a concrete example command, leaving the entry-point step as high-level direction.

4 / 5

Workflow Clarity

The Quick Start sequence (restore before create, preserve markers, re-read before decisions, one plan owner), the creation contract with 'Validation must succeed before substantive work and after changing phase structure', the 3-Strike escalation protocol, and error-logging rules give a clear sequence with most checkpoints present. Not 5 because the FIRST section — the actual entry point — packs plan resolution, catchup, parallel-host pinning, and orchestrator/worker roles into one paragraph with implicit checkpoints, and the destructive archive operation's guard ('Never archive on age or completion alone') relies on prose rather than an explicit validate step.

4 / 5

Progressive Disclosure

The section structure is good and references are one level deep and clearly signaled ('Manus Principles: See references/reference.md', 'Real Examples: See references/examples.md', plan-inventory.md), and all three referenced `references/` files exist in the bundle. But scored against the actual bundle, the Templates section's links to `templates/task_plan.md`, `templates/findings.md`, and `templates/progress.md` are dead — no `templates/` directory ships in the bundle — so half of the body's file references point at nonexistent paths while the text says 'Copy these templates to start'. That is more than the 'minor organization gaps' of anchor 4; not 2 because the in-body content is well placed and the existing references are properly signaled.

3 / 5

Total

15

/

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.

A third-person, concrete description that clearly names the skill's files and mechanisms and includes an explicit 'Use for' clause, but its trigger coverage is narrow and parts of the budget are spent on security caveats instead of user-facing capabilities. It lands at 4 on specificity, completeness, and distinctiveness, and 3 on trigger-term quality.

Suggestions

Broaden the 'Use for' clause with natural user-spoken triggers (e.g., 'multi-step tasks, task tracking, staying organized across long sessions, or resuming interrupted work') instead of only 'research or work needing 5+ tool calls'.

Trim the security-boundary sentences ('no network upload path', 'never runs commands declared in Markdown') to make room for capability coverage — they are scope disclaimers, not what/when information.

Reduce implementation jargon like 'nonce-framed excerpts' and 'gated mode' in favor of terms users would recognize when deciding to invoke the skill.

DimensionReasoningScore

Specificity

It lists several specific concrete actions with named 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 and emits aggregate counts only'. Not 5 because a large share of the description is spent on scope/security caveats ('no network upload path', 'never runs commands declared in Markdown') rather than capabilities, leaving coverage of what the skill actually does for the user less comprehensive than the anchor-5 examples.

4 / 5

Completeness

Both parts are explicitly present: the 'what' is concrete ('Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject...') and the 'when' is an explicit clause ('Use for research or work needing 5+ tool calls.'). It is not 5 because the when-clause is thin — only two triggers, one of them an internal metric users would not naturally phrase — whereas anchor 5 demands concrete trigger phrases like 'when the user mentions PDFs, forms, or document extraction'.

4 / 5

Trigger Term Quality

Some relevant natural keywords are present — 'planning', 'multi-step', 'research', 'work needing 5+ tool calls' — but common variations a user would actually say are missing: 'task tracking', 'todo', 'project', 'stay organized', 'resume', 'session'. '5+ tool calls' and 'nonce-framed excerpts' are agent/implementation jargon rather than user-spoken trigger phrases. This matches 'Some relevant keywords but missing common variations or synonyms', and falls well short of anchor 4's good natural-term coverage.

3 / 5

Distinctiveness Conflict Risk

The named file trio (task_plan.md, findings.md, progress.md), the hook-injection mechanism, and session-catchup.py give it a clear niche with distinct triggers and minimal conflict risk against unrelated skills. Not 5 because 'planning' and 'research' are broad triggers that overlap with general task-organization and project-planning skills, matching 'mostly distinct; minor overlap risk with closely related skills' rather than a fully unambiguous niche.

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

Warning

Total

14

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

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