writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
44
46%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/writing-plans/SKILL.mdQuality
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 incomplete—it only provides a vague 'when' trigger without explaining what the skill actually does. The lack of concrete actions, specific outputs, or a clear domain makes it nearly impossible for Claude to reliably select this skill over others. It 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 coding tasks, dependencies, and acceptance criteria.'
Include a broader set of natural trigger terms users would say, such as 'plan', 'implementation plan', 'task breakdown', 'decompose requirements', 'before coding', 'project planning'.
Rewrite to clearly answer both 'what' and 'when', e.g., 'Decomposes specifications and requirements into ordered implementation steps with clear subtasks. Use when the user has a spec, PRD, or requirements document and wants to plan their coding approach before writing code.'
| 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'. '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 mention, but misses many common variations like 'plan', 'breakdown', 'implementation plan', 'architecture', 'design doc', or 'before coding'. | 2 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic—'multi-step task' and 'before touching code' could apply to planning, architecture, task decomposition, code review, or many other skills. It provides no clear niche to distinguish it from other pre-coding or planning skills. | 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 skill that provides highly actionable guidance for writing implementation plans. Its greatest strengths are the concrete task structure template with TDD workflow and the self-review checklist with explicit validation steps. Minor weaknesses include some redundancy between sections and a slightly monolithic structure that could benefit from splitting the task template into a reference file.
Suggestions
Remove the 'Remember' section or merge its unique points into the relevant earlier sections to reduce redundancy.
Consider extracting the task structure template and no-placeholders rules into a referenced file (e.g., PLAN-TEMPLATE.md) to improve progressive disclosure.
| 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, TDD). The 'No Placeholders' section is valuable but slightly verbose. The overview paragraph explaining the target audience could be tighter. | 2 / 3 |
Actionability | Highly actionable with concrete examples throughout: the task structure template shows exact markdown format with executable code blocks, test commands with expected output, commit commands, and file path conventions. The plan document header template is copy-paste ready. | 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 provides explicit validation checkpoints (spec coverage, placeholder scan, type consistency). The task granularity section defines precise 2-5 minute steps with TDD feedback loops (write test → verify fail → implement → verify pass → commit). | 3 / 3 |
Progressive Disclosure | The skill references external skills (superpowers-ruby:subagent-driven-development, superpowers-ruby:executing-plans) and a brainstorming skill appropriately, but the content itself is somewhat monolithic — the task structure template, no-placeholders rules, and self-review checklist could potentially be split out. However, at ~120 lines it's borderline acceptable as a single file. No bundle files are provided to support progressive disclosure. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%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
c037ce3
- Reviewed
Table of Contents
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.