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 ./.opencode/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 body is highly actionable with concrete commands, an exact plan format contract, validation gates, and a well-designed error-escalation protocol. Its weaknesses are redundancy — the same read/write and persistence rules are restated across Critical Rules, the decision matrix, the reboot test, and anti-patterns — and dead references: most linked markdown files (templates, reference.md, examples.md, plan-inventory.md, docs/opencode.md) are missing from the bundle even though all referenced scripts exist.

Suggestions

Ship or fix the referenced files — templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, plan-inventory.md, and docs/opencode.md — since the body directs readers to copy the templates and consult these docs, and none are present in the bundle.

Consolidate the overlapping guidance sections: Critical Rules 3/4, the Read vs Write Decision Matrix, the 5-Question Reboot Test, and the Anti-Patterns table each restate "re-read the plan before deciding" and "persist to files"; merging them into one section would cut tokens without losing clarity.

Move the OpenCode-specific installation and plugin details into the referenced docs/opencode.md and keep a one-line pointer in the body, since they are only relevant to a subset of hosts.

DimensionReasoningScore

Conciseness

Mostly efficient — tables, terse rules, exact commands — but the same guidance is stated three or more times across sections: "Read Before Decide" (Critical Rules 3) reappears as the decision-matrix row "Starting new phase → Read plan/findings" and again as the anti-pattern "State goals once and forget → Re-read plan before decisions"; the RAM/Disk core pattern is restated by "Stuff everything in context → Store large content in files". Consolidating Critical Rules, the Read vs Write matrix, the 5-Question Reboot Test, and Anti-Patterns would remove noticeable redundancy. Not 4 because the repetition is across multiple full sections, not minor instances.

3 / 5

Actionability

Fully executable, copy-paste-ready guidance in both bash and PowerShell: the session-catchup discovery loop, `sh "$PWF_SKILL_DIR/scripts/init-session.sh"`, `check-complete.sh --validate path/to/task_plan.md`, `set-active-plan.sh --list` / `--archive <id>` / `--restore <id>`, all of which reference scripts that actually exist in the bundle's scripts/ directory. The plan format is pinned exactly ("### Phase N: Name with exactly one **Status:** pending/in_progress/complete line"), covering creation, validation, and archival cases.

5 / 5

Workflow Clarity

Clear sequence with explicit validation gates and feedback loops: restore-before-create ordering in FIRST and Quick Start steps 1–4, the creation contract requiring "Validation must succeed before substantive work and after changing phase structure", the 3-Strike error protocol with escalation after 3 failures, and the semi-destructive archive flow gated by user approval with a preview (`--archive` previews, `--yes` applies). This matches the anchor for explicit validation steps plus error-recovery feedback loops.

5 / 5

Progressive Disclosure

References are clearly signaled and one level deep ("See [reference.md](reference.md)", "See [examples.md](examples.md)", templates listed under Templates), but the referenced files do not exist in the bundle: templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, plan-inventory.md, and docs/opencode.md are all absent — only the scripts/ directory ships. A reader following "Copy these templates to start" or "See reference.md" hits dead paths, which is more than the "minor organization gaps" of level 4. Not 2 because the in-body structure and signaling are good and the scripts that are referenced do exist.

3 / 5

Total

16

/

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 answers what and when explicitly and is distinctive via named planning files, but roughly half its length is privacy/boundary disclaimers (metadata behavior, nonce framing, no network path) that read as review-response boilerplate rather than capability description. This crowds out the natural trigger terms and capability coverage that would make it highly effective. Third-person voice is used correctly throughout.

Suggestions

Add natural trigger phrases users would actually say — e.g. "Use when starting multi-step tasks, research projects, or project work that spans many steps" — instead of relying solely on "work needing 5+ tool calls", which users cannot self-assess.

Trim the privacy/boundary sentences (metadata modes, nonce framing, no network upload) to one short clause or move them to the body; they consume most of the description without helping a user decide when to invoke the skill.

Replace jargon ("gated mode", "nonce-framed excerpts", "lifecycle hooks") with plain-language capability terms, and briefly mention phase tracking and progress updates so the "what" covers what the skill actually does.

DimensionReasoningScore

Specificity

Concrete actions are named — "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" — with named files and scripts. Falls short of 5 because the middle of the description is consumed by privacy boundary statements ("no network upload path", "never runs commands declared in Markdown") rather than comprehensive coverage of the skill's actual planning capabilities (phase tracking, error logging, plan archival).

4 / 5

Completeness

Both parts are present: the "what" is explicit ("Persistent file-based planning... Keeps task_plan.md, findings.md, and progress.md on disk") and the "when" is an explicit trigger clause ("Use for research or work needing 5+ tool calls"). Not 5 because the "when" is narrow — a user cannot easily self-diagnose "5+ tool calls", and the concrete trigger phrases from the body (multi-step tasks, building projects) are absent — and the "what" is diluted by the security-compliance sentences.

4 / 5

Trigger Term Quality

Some natural keywords appear ("planning", "multi-step", "research", "task_plan.md"), but the description is dominated by technical jargon users would never say ("nonce-framed excerpts", "gated mode", "lifecycle hooks", "--metadata"), and common natural variations like "task plan", "todo", "project tracking", or "stay organized" are missing. Not 4 because the natural-term coverage is thin relative to the jargon density; not 2 because "planning", "multi-step", and "research" are genuine user phrases.

3 / 5

Distinctiveness Conflict Risk

Naming the specific planning files (task_plan.md, findings.md, progress.md) and the session-catchup.py script carves out a clear niche distinct from generic todo/list skills. Not 5 because "planning for multi-step AI-agent work" still overlaps broadly with other planning and task-management skills whose descriptions also mention planning and persistence.

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

Warning

Total

14

/

16

Passed

Repository

OthmanAdi/planning-with-files

Path

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