planning-with-files

Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; Gemini 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. The session-end hook reports status only; it does not request continuation or run commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls.

Quality

72%

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 ./.gemini/skills/planning-with-files/SKILL.md

Quality

Content

66%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 clear, well-sequenced planning workflow with concrete commands and a genuine error-recovery feedback loop, and it points to real reference files one level deep. Its main weaknesses are the broken templates/ references that undercut the primary getting-started path, repeated security restatements, and inline version clutter.

Suggestions

Ship the actual templates/task_plan.md, templates/findings.md, and templates/progress.md files (or remove the six links and inline minimal template skeletons), since the Quick Start depends on them.

Consolidate the security-boundary guidance repeated in the intro, session-catchup section, and Security Boundary section into the single Security Boundary table.

Move version numbers and issue references (v2.36.1, v2.37.0, issue #237) out of the body into a changelog or the metadata block to cut token cost without losing information.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining concepts Claude already knows and uses dense tables, but security-boundary statements are repeated across the intro, session-catchup, and Security Boundary sections, and inline version/date-sensitive details ("v2.36.1", "v2.37.0", "issue #237") pad the token budget without a deprecated/old-patterns section.	3 / 5
Actionability	Several concrete, copy-paste commands are provided (session-catchup.py invocation, init-session.sh with name args, set-active-plan --list, attest-plan.sh), but the templates are central guidance ("Copy these templates to start") and all six links point to a templates/ directory that does not exist in the bundle, which is a key missing detail rather than a minor gap.	3 / 5
Workflow Clarity	The sequence is explicit and ordered (restore state first, create plan, re-read before decisions, update after each phase) with a validation command (check-complete.sh) and a full feedback loop in the 3-Strike Error Protocol (diagnose, alternative approach, rethink, escalate to user); the skill is documentation/planning, so no destructive-operation cap applies.	5 / 5
Progressive Disclosure	Structure is good with well-labeled sections and one-level-deep references that exist (references/reference.md, references/examples.md) plus accurate inline script descriptions, but the missing templates/ folder leaves the Templates and Quick Start sections pointing at nonexistent files — more than a minor organization gap, keeping this below 5.	4 / 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.

The description answers what the skill does and when to use it with mostly concrete, third-person language, but it spends disproportionate length on security caveats while its trigger vocabulary is thin and slightly unnatural. It is a solid, distinguishable description that would benefit from broader, user-natural trigger phrasing.

Suggestions

Replace or supplement "work needing 5+ tool calls" with natural trigger phrasing users would actually say, e.g., "Use when a task has 3+ steps, spans sessions, or requires tracking progress and findings."

Trim the security-boundary sentences (nonce framing, no network upload path) to one short clause and use the freed space to enumerate more user-facing capabilities (e.g., parallel named plans, plan attestation).

Add common synonyms such as "plan", "task tracking", "session recovery", and "working memory" to widen natural keyword coverage.

Dimension	Reasoning	Score
Specificity	Concrete actions are named ("Keeps task_plan.md, findings.md, and progress.md on disk", "reads same-project local agent session records and emits aggregate counts only") and stay in third person, but roughly half the description is security-boundary disclaimers rather than capability coverage, leaving minor gaps.	4 / 5
Completeness	The "what" is clear ("Persistent file-based planning for multi-step AI-agent work") and an explicit when-clause is present ("Use for research or work needing 5+ tool calls"), so both are answered; the "when" is narrow and could be more specific, matching the anchor for 4 rather than the fully concrete 5.	4 / 5
Trigger Term Quality	Relevant keywords exist ("planning", "multi-step", "research") but common natural variations users would actually say are missing (e.g., "plan", "track progress", "long task", "resume work"), and the main trigger phrase "work needing 5+ tool calls" is phrasing a user would not naturally say.	3 / 5
Distinctiveness Conflict Risk	The planning-file niche is distinct (named files, hook injection, session recovery) with limited overlap risk against similar todo/planning skills; only minor overlap with generic productivity or context-management skills keeps it below 5.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 6 missing	Warning

	Total	15 / 16 Passed

Repository: OthmanAdi/planning-with-files
Path: .gemini/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.