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

Discovery

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 only provides a vague 'when' trigger without explaining what the skill actually does. It lacks any concrete actions, specific outputs, or distinguishing characteristics that would help Claude select it from a pool of skills. The description reads more like a partial usage hint than a proper skill description.

Suggestions

Add explicit capability statements describing what the skill does, e.g., 'Breaks down specs and requirements into an ordered implementation plan with discrete, testable steps' or similar concrete actions.

Add a clear 'what it does' section before the 'Use when' clause, listing specific outputs like 'generates task lists, identifies dependencies, creates implementation order'.

Include more distinctive trigger terms and natural keywords such as 'planning', 'implementation plan', 'task breakdown', 'decompose requirements', 'step-by-step plan' to improve both trigger quality and distinctiveness.

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions at all. It doesn't say what the skill does—there are no verbs describing capabilities like 'generates', 'plans', 'breaks down', etc. 'Multi-step task' is extremely vague.	1 / 3
Completeness	The description only addresses 'when' (before touching code, when you have a spec) but completely omits 'what' the skill actually does. There is no explanation of the skill's capabilities or outputs.	1 / 3
Trigger Term Quality	It includes some relevant terms like 'spec', 'requirements', and 'multi-step task' that users might naturally say, but misses many common variations such as 'plan', 'design', 'architecture', 'breakdown', 'implementation plan', 'task planning', etc.	2 / 3
Distinctiveness Conflict Risk	The description is extremely generic—'multi-step task' and 'before touching code' could apply to many skills such as architecture planning, task decomposition, code review, project scaffolding, etc. It provides no clear niche.	1 / 3
	Total	5 / 12 Passed

Implementation

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, well-structured planning skill that provides highly actionable guidance with concrete examples and clear workflow sequencing. Its main weakness is moderate verbosity — some points are repeated across sections, and the 'Remember' section largely restates earlier content. The self-review checklist is a particularly valuable validation checkpoint that elevates the workflow clarity.

Suggestions

Remove the 'Remember' section since its four bullet points are already covered in detail by earlier sections (File Structure, Task Structure, No Placeholders), saving tokens without losing information.

Consider extracting the detailed task structure template and no-placeholders anti-patterns into a referenced file (e.g., PLAN-TEMPLATE.md) to keep the main skill focused on the workflow and decision-making process.

Dimension	Reasoning	Score
Conciseness	Generally efficient but has some redundancy — the 'Remember' section repeats points already made in earlier sections (exact file paths, complete code, DRY/YAGNI/TDD). Some sections like 'No Placeholders' could be tighter. However, most content earns its place given the complexity of the task.	2 / 3
Actionability	Highly actionable with concrete examples throughout: exact task structure with executable code blocks, specific pytest commands with expected output, git commit examples, file path conventions, and a complete plan document header template. The 'No Placeholders' section provides specific anti-patterns to avoid.	3 / 3
Workflow Clarity	Excellent multi-step workflow: clear sequence from scope check → file structure → task decomposition → plan writing → self-review → execution handoff. The self-review section serves as an explicit validation checkpoint with a concrete checklist. The TDD cycle within each task (write failing test → verify fail → implement → verify pass → commit) is a well-defined feedback loop.	3 / 3
Progressive Disclosure	The skill references two sub-skills (subagent-driven-development, executing-plans) and a git-worktrees skill, which is good progressive disclosure. However, all content is inline in a single file that's fairly long (~120 lines of substantive content). The file structure, task granularity, and no-placeholders sections could potentially be split into referenced files for cleaner navigation, though the monolithic approach is defensible for a planning skill.	2 / 3
	Total	10 / 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: obra/superpowers
Commit: f2cbfbe

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