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

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.opencode/skills/planning-with-files/SKILL.md

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-sequenced, largely executable planning workflow with genuine error-recovery loops and tight tables, and every referenced script exists. It is held back by padding (Manus/RAM-disk analogies, repeated placement notes) and by a progressive-disclosure layer that points to template and reference files that are missing from the bundle.

Suggestions

Ship the referenced files (templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md) or remove/inline their mentions so every link in the body resolves.

Trim concept-level padding Claude already knows: the 'Work like Manus' line, the Context-Window-=-RAM analogy, and the duplicated where-files-go note.

Make verification an explicit workflow step, e.g., add a final Quick Start step: run scripts/check-complete.sh after each phase and on completion, and act on its output before proceeding.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient tables and rules, but includes explanations Claude does not need: "Work like Manus: Use persistent markdown files as your 'working memory on disk.'", the "Context Window = RAM / Filesystem = Disk" analogy, and a duplicated note ("Planning files go in your project root, not the skill installation folder" repeats the Where Files Go section). Not 4 because there are several such instances of padding and repetition; not 2 because most sections are genuinely tight and operational.	3 / 5
Actionability	Concrete executable guidance dominates: full bash and PowerShell restore blocks calling session-catchup.py --metadata, `scripts/init-session.sh "Task Name"`, `scripts/check-complete.sh`, and `sh "<skill-dir>/scripts/set-active-plan.sh" --list`. Not 5 because the referenced templates (templates/task_plan.md, findings.md, progress.md) do not exist in the bundle, and some steps remain high-level ("Use the templates in that directory and preserve existing work") without the concrete expected file contents.	4 / 5
Workflow Clarity	The Quick Start is a clearly numbered 4-step sequence, the restore-first section pins plan-directory resolution before any work, and the 3-Strike Error Protocol plus "Log ALL Errors" rule give explicit error-recovery feedback loops. Not 5 because verification is a named script (check-complete.sh) rather than an explicit checkpoint woven into the sequence (when to run it and what to do on failure is left implicit); not 3 because sequencing and error handling are far more complete than a bare step list.	4 / 5
Progressive Disclosure	The body is well structured with clearly signaled, one-level-deep references (Templates, Scripts, Advanced Topics, Anti-Patterns sections), but the referenced files — templates/task_plan.md, templates/findings.md, templates/progress.md, reference.md, examples.md, and docs/opencode.md — are absent from the bundle; only the scripts/ references resolve to real files. Not 4 because navigation to the referenced advanced material is broken; not 2 because the in-body structure and signaling are themselves good and most operational content lives appropriately inline.	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 distinct, naming concrete files and behaviors with a correct third-person voice and an explicit trigger clause. Its main weaknesses are a trigger line ("Use for research or work needing 5+ tool calls") that lacks natural user phrasing and synonyms, and a middle section devoted to security caveats that crowds out a fuller statement of what the skill does.

Suggestions

Expand the trigger line with natural phrases users would actually say, e.g., "Use when starting multi-step research, project builds, or long tasks that need a persistent task plan, findings log, and progress tracking".

Replace some of the security-caveat sentences (network path, gated-mode guarantees) with one or two concrete capability statements drawn from the body, such as initializing a plan with scripts/init-session.sh and verifying completion with scripts/check-complete.sh.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions — "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", "--replay may emit bounded nonce-framed excerpts" — but coverage is skewed toward security caveats rather than comprehensively describing what the skill does. Not 5 because the actual planning workflow (templates, plan initialization, phase tracking) is not described; not 3 because multiple concrete, verifiable actions are named.	4 / 5
Completeness	The "what" is clearly stated ("Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk") and a "when" clause is present ("Use for research or work needing 5+ tool calls"), but the trigger guidance is a single narrow clause with no concrete trigger phrases. Not 5 because the "when" is terse and could be much more explicit about the situations that call for this skill; not 3 because both what and when are explicitly present.	4 / 5
Trigger Term Quality	Relevant keywords exist — "planning", "multi-step", "research", "5+ tool calls" — but common natural variations users would say are missing (e.g., "task plan", "project planning", "progress tracking", "context management"). Not 4 because "5+ tool calls" is not a phrase a user would naturally say and synonyms are sparse; not 2 because there are several genuinely relevant keywords, not just generic ones.	3 / 5
Distinctiveness Conflict Risk	Named planning files (task_plan.md, findings.md, progress.md) and specific behaviors (lifecycle hook injection, session-catchup.py modes) carve out a recognizable niche distinct from generic todo or documentation skills. Not 5 because "multi-step AI-agent work" still overlaps with general task-management and orchestration skills; not 3 because the named files and unique mechanisms make confusion unlikely.	4 / 5
	Total	15 / 20 Passed

Validation

87%

Warnings & errors only

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

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 5 missing	Warning

	Total	14 / 16 Passed

Repository: OthmanAdi/planning-with-files
Path: .opencode/skills/planning-with-files/SKILL.md
Commit: dab9d16

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.