planning-with-files

Use this by default for non-trivial multi-step work that needs persistent planning, progress tracking, or durable notes on disk. Trigger when a task will likely span multiple tool calls, research steps, verification loops, or enough context that the plan should not live only in transient chat memory.

Quality

64%

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 ./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 is well-structured and actionable with ready-to-use templates and a clear workflow loop, but it carries redundant/preachy prose and references bundle files that are absent, limiting conciseness and progressive-disclosure scores.

Suggestions

Remove the 'Critical Rules' section or fold its unique points into 'Quick Start'/'Core Workflow' to eliminate redundancy and tighten conciseness.

Either create the referenced reference.md and examples.md files with the advanced/error-recovery content moved out of SKILL.md, or drop the dangling references so signaling matches the actual bundle.

Move the full task_plan.md and notes.md templates into reference.md, keeping only a minimal inline example in SKILL.md, to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but padded in places — 'Critical Rules' restates 'Quick Start' and 'Core Workflow', and lines like 'This is not just an optional planning style. It should be the default persistence layer' are preachy filler that could be trimmed.	3 / 5
Actionability	Provides concrete, copy-paste-ready templates (task_plan.md, notes.md) and a 3-file pattern table; the bash snippets ('Read task_plan.md') are illustrative rather than literal commands, leaving minor gaps below a 5.	4 / 5
Workflow Clarity	Clear Loop 1-4 sequence with checkpoints (read before decide, update after act, log errors); this is a planning skill, not a destructive/batch operation, so the validation cap does not apply, but there is no hard validate-fix-retry loop to reach 5.	4 / 5
Progressive Disclosure	Section structure exists and references to reference.md/examples.md are signaled with content bullets, but those referenced files do not exist in the bundle and templates/anti-patterns are inlined that could live in separate files.	3 / 5
	Total	14 / 20 Passed

Description

66%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 clearly communicates intent with explicit trigger guidance covering both what and when, but its capability language stays abstract and its trigger scope is broad enough to risk overlap with other task-management skills.

Suggestions

Add one concrete file-level action to the 'what' clause (e.g. 'creates and maintains task_plan.md and notes.md files') to lift specificity toward a 4-5.

Narrow the trigger scope or add a distinguishing phrase (e.g. 'when the plan should persist on disk across sessions') to reduce overlap with in-context TodoWrite-style tools.

Dimension	Reasoning	Score
Specificity	Names the domain and capabilities ('persistent planning, progress tracking, or durable notes on disk') but describes abstract capabilities rather than concrete file-level actions, fitting 'names domain and 1-2 concrete actions, not comprehensive'.	3 / 5
Completeness	Explicitly answers both what ('persistent planning, progress tracking, or durable notes on disk') and when ('Trigger when a task will likely span multiple tool calls, research steps, verification loops'); the 'what' is slightly abstract, keeping it just below a 5.	4 / 5
Trigger Term Quality	Good coverage of natural trigger terms a user would say ('multi-step work', 'planning', 'progress tracking', 'multiple tool calls', 'research steps', 'verification loops'); below 5 because terms lean abstract with no synonyms or file extensions.	4 / 5
Distinctiveness Conflict Risk	The trigger 'non-trivial multi-step work' is broad and overlaps with general task-management skills (e.g. TodoWrite), so it is somewhat specific but could still conflict with similar skills.	3 / 5
	Total	14 / 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: 2 missing	Warning

	Total	14 / 16 Passed

Repository: Galaxy-Dawn/claude-scholar
Path: skills/planning-with-files/SKILL.md
Commit: 6ed46da

Reviewed: 8 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.