writing-plans

Use when you have a spec or requirements for a multi-step task, before touching code

Quality

46%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/writing-plans/SKILL.md

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a strong, highly actionable skill that provides clear workflow guidance for writing implementation plans. Its greatest strengths are the concrete task structure template with executable examples and the well-defined self-review validation checkpoint. Minor weaknesses include some redundancy between sections and a monolithic structure that could benefit from splitting the template and checklist into separate referenced files.

Suggestions

Remove the 'Remember' section or merge its unique points into the relevant earlier sections to eliminate redundancy.

Consider extracting the task structure template and self-review checklist into separate bundle files (e.g., TASK_TEMPLATE.md, SELF_REVIEW.md) to improve progressive disclosure and keep the main skill leaner.

Dimension	Reasoning	Score
Conciseness	Generally efficient but has some redundancy — the 'Remember' section repeats points already made in prior sections (exact file paths, complete code, TDD, frequent commits). The overview's characterization of the target engineer ('questionable taste') is flavor text that doesn't add actionable value. Some sections like 'No Placeholders' could be tighter.	2 / 3
Actionability	Highly actionable with concrete task structure templates showing exact code, exact commands with expected output, file path conventions, commit message format, and a complete plan document header template. The task structure example is copy-paste ready and leaves no ambiguity about what each step should contain.	3 / 3
Workflow Clarity	Excellent multi-step workflow: scope check → file structure mapping → task decomposition → plan writing → self-review → execution handoff. The self-review section serves as an explicit validation checkpoint with specific checks (spec coverage, placeholder scan, type consistency). The execution handoff provides clear branching with required sub-skills for each path.	3 / 3
Progressive Disclosure	References to external skills (subagent-driven-development, executing-plans, brainstorming) are clearly signaled, and the plan output location is specified. However, the skill itself is a single monolithic file (~120 lines) that could benefit from separating the task structure template and self-review checklist into referenced files. No bundle files are provided to support the references made.	2 / 3
	Total	10 / 12 Passed

Description

14%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description is critically weak because it completely omits what the skill does, providing only a vague trigger condition. Without any concrete actions or capabilities listed, Claude cannot make an informed decision about when to select this skill. The description reads more like a partial usage hint than a proper skill description.

Suggestions

Add explicit capability descriptions: what does this skill actually do? E.g., 'Breaks down specifications into an ordered implementation plan with discrete tasks, identifies dependencies, and creates a step-by-step coding roadmap.'

Expand trigger terms with natural user language variations such as 'plan', 'break down', 'implementation steps', 'architecture', 'design doc', 'task breakdown', 'project planning'.

Add a clear 'Use when...' clause that distinguishes this from other planning or code-related skills, e.g., 'Use when the user provides a spec, PRD, or requirements document and wants a structured implementation plan before writing code.'

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions at all. It doesn't say what the skill does—only vaguely when to use it. 'Multi-step task' and 'before touching code' are abstract and don't describe any specific capabilities.	1 / 3
Completeness	The 'what does this do' is entirely missing—there is no description of capabilities or actions. It only provides a vague 'when' clause without explaining what the skill actually does.	1 / 3
Trigger Term Quality	It includes some relevant terms like 'spec', 'requirements', and 'multi-step task' that users might naturally mention. However, it's missing common variations like 'plan', 'design', 'architecture', 'breakdown', 'implementation plan', etc.	2 / 3
Distinctiveness Conflict Risk	The description is extremely generic—'multi-step task' and 'before touching code' could apply to planning, architecture, design, task decomposition, or many other skills. It would easily conflict with other planning or analysis skills.	1 / 3
	Total	5 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: lucianghinda/superpowers-ruby
Commit: 712d734

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