Tessl • The management layer for AI agent skills

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

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

The canonical home for this skill is planning-with-files in OthmanAdi/planning-with-files

Quality

Content

52%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 genuinely actionable workflows with explicit validation gates and error-recovery loops, and its script commands are concrete and executable. However, it is bloated with changelog-style version history and design rationale, and its progressive disclosure is broken in practice: seven referenced markdown/template files are missing from the bundle while deep reference material is inlined.

Suggestions

Ship the referenced files or fix the links: templates/task_plan.md, templates/findings.md, templates/progress.md, templates/loop.md, reference.md, examples.md, and plan-inventory.md are all cited but absent from the bundle.

Move the v3 hardening, host capability tiers, unchanged-view suppression, parallel-write guard, and turn-loop integration sections into a separate reference file, leaving SKILL.md a lean overview with one-level-deep pointers.

Strip version numbers and issue/PR history ("v2.42.0 clarification", "issue #178", "PR #180 lesson") from the instructional text, or consolidate them into a dedicated changelog/deprecated section, and collapse the four overlapping plan-restoration explanations into one canonical sequence.

Dimension	Reasoning	Score
Conciseness	The ~500-line body is noticeably verbose: it is littered with version numbers and changelog references ("v3.24.0", "v2.42.0 clarification", "issue #237", "PR #180 lesson") and long design-rationale essays ("This is the lesson from issue #178: an incomplete plan is a normal state...") that are history, not instruction. Core sections like File Purposes and Critical Rules are efficient, keeping it above the severely-padded anchor.	2 / 5
Actionability	Guidance is mostly executable: exact commands ("sh \"$PWF_SKILL_DIR/scripts/init-session.sh\"", "session-catchup.py --metadata \"$(pwd)\""), a 6-step manual /plan-goal procedure, and a precise phase format contract ("exactly one Status: pending... line"). The minor gap is that the templates the body tells the agent to copy are not shipped in this bundle.	4 / 5
Workflow Clarity	Multi-step processes are clearly sequenced with real checkpoints: numbered restore steps, "Validation must succeed before substantive work and after changing phase structure", the 3-Strike Error Protocol as an error-recovery feedback loop, and check-complete.sh verification. It falls short of the top anchor because the mainline workflow is scattered across overlapping sections (plan restoration is re-explained in at least four places).	4 / 5
Progressive Disclosure	Checked against the actual bundle: the templates/ directory does not exist, so the links to templates/task_plan.md, templates/findings.md, templates/progress.md, and templates/loop.md are dead, as are the reference.md, examples.md, and plan-inventory.md links — only the scripts/ references resolve. Meanwhile ~300 lines of v3 hardening, host-capability-tier, and turn-loop integration detail that clearly belongs in separate reference files are inlined in SKILL.md.	2 / 5
	Total	12 / 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 both what and when with concrete file names and an explicit use threshold, and is clearly distinguishable from other skills. Its weaknesses are a jargon-heavy middle section aimed at security review rather than trigger matching, and a single narrow when-clause instead of broader natural trigger phrases.

Suggestions

Replace the security-policy sentences ('never runs commands declared in Markdown', 'no network upload path') with capability-oriented actions, and move that boundary detail into the SKILL.md body where it already exists.

Broaden the 'Use for...' clause with natural trigger phrases users would actually say, e.g. 'Use for multi-step tasks, research, project work, or any task needing 5+ tool calls'.

Trim technical jargon like 'bounded nonce-framed excerpts' and 'session-catchup.py --metadata' from the description; keep tool names in the body where the commands are shown.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — "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 only" — but capability coverage is diluted by implementation caveats like "The skill has no network upload path" rather than rounding out the action list, so it falls short of the comprehensive anchor.	4 / 5
Completeness	Both parts are explicitly present: the what ("Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk") and the when ("Use for research or work needing 5+ tool calls"). The when-clause is explicit but narrow — a single trigger condition rather than the multiple concrete trigger phrases of the top anchor.	4 / 5
Trigger Term Quality	Some natural keywords appear ("planning", "multi-step", "research", "5+ tool calls"), but the middle of the description is technical jargon no user would say ("bounded nonce-framed excerpts", "session-catchup.py --metadata") and common natural variations like "task tracking", "long-running tasks", or "project organization" are missing.	3 / 5
Distinctiveness Conflict Risk	Named artifacts (task_plan.md, findings.md, progress.md, PLAN_ID, .planning/) carve a clear niche distinct from most skills, but the broad "planning" framing carries minor overlap risk with todo/plan/task-management skills, matching "mostly distinct; minor overlap risk".	4 / 5
	Total	15 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (535 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: .pi/skills/planning-with-files/SKILL.md
Revision: 51bf62d

Reviewed: 2 days ago

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.

planning-with-files

Table of Contents

Is this your skill?