writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Quality

37%

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-skills/SKILL.md

Quality

Discovery

40%

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 serves only as a trigger clause ('Use when...') without explaining what the skill actually does, leaving the 'what' component entirely missing. The language is vague — 'creating', 'editing', and 'verifying skills' doesn't convey concrete actions or outputs. It needs both a capability summary and more specific trigger terms to be effective for skill selection.

Suggestions

Add a 'what does this do' clause before the 'Use when' clause, e.g., 'Generates, validates, and updates SKILL.md files with proper YAML frontmatter, structured instructions, and best practices.'

Include more specific trigger terms users would naturally say, such as 'SKILL.md', 'skill file', 'skill template', 'write a new skill', 'test skill', or 'skill frontmatter'.

Specify what 'verifying skills work' means concretely, e.g., 'validates YAML frontmatter syntax, checks required fields, and tests skill structure against the schema'.

Dimension	Reasoning	Score
Specificity	The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what a 'skill' is, what creating one involves, or what verification entails.	1 / 3
Completeness	The description functions as a 'Use when...' clause addressing when to use the skill, but it lacks a clear 'what does this do' component. There's no explanation of what the skill actually does — only when to invoke it.	2 / 3
Trigger Term Quality	It includes some relevant keywords like 'skills', 'creating', 'editing', and 'deployment', but misses natural variations users might say such as 'SKILL.md', 'skill file', 'write a skill', 'test a skill', 'skill template', or 'frontmatter'.	2 / 3
Distinctiveness Conflict Risk	The term 'skills' provides some specificity, but 'creating', 'editing', and 'verifying' are generic actions that could overlap with many other skills. Without more detail about what kind of skills or what format, there's moderate conflict risk.	2 / 3
	Total	7 / 12 Passed

Implementation

35%

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

This skill suffers primarily from extreme verbosity - it's a meta-skill about writing concise skills that is itself deeply unconcise. It repeats core concepts multiple times (the Iron Law appears 3+ times, TDD mapping is restated in multiple forms), includes extensive rationalization tables and anti-pattern sections that bloat the document, and explains concepts Claude already understands well (TDD, file organization, what flowcharts are for). The workflow structure is reasonable but lacks concrete executable validation steps, deferring the actual testing methodology to an unreachable external file.

Suggestions

Cut content by 60%+: Remove the rationalization tables, anti-pattern examples, and repeated Iron Law statements. The TDD mapping table and the RED-GREEN-REFACTOR section say the same thing twice.

Make the testing workflow executable: Instead of referencing testing-skills-with-subagents.md, include a minimal concrete example of how to actually run a pressure scenario with a subagent (specific command or code).

Split the CSO section and bulletproofing section into separate reference files - they are heavy reference material (100+ lines each) that the skill's own guidelines say should be in supporting files.

Practice what you preach on token efficiency: The skill advises <500 words for non-frequently-loaded skills but is 5x that length. Apply the compression techniques described in the Token Efficiency section to this skill itself.

Dimension	Reasoning	Score
Conciseness	This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a skill is, basic file organization), includes extensive rationalization tables, repeats the 'Iron Law' multiple times, and has significant redundancy between sections. The token efficiency section ironically exists in one of the most token-inefficient skills possible.	1 / 3
Actionability	The skill provides some concrete guidance (YAML frontmatter examples, directory structures, naming conventions) but lacks executable code for the core workflow. The testing methodology references external files rather than providing concrete commands. The checklist is actionable but the actual skill creation steps are more philosophical than executable.	2 / 3
Workflow Clarity	The RED-GREEN-REFACTOR workflow is clearly sequenced and the checklist at the end provides good structure. However, the validation steps are vague ('run scenarios WITH skill - verify agents now comply') without specifying how to actually run these scenarios or what compliance looks like concretely. The testing methodology is deferred to an external file (testing-skills-with-subagents.md) rather than included.	2 / 3
Progressive Disclosure	The skill references several external files (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot, render-graphs.js) which is good progressive disclosure in principle. However, no bundle files are provided, making it impossible to verify these references resolve. The main SKILL.md itself contains far too much inline content that could be split out (the entire CSO section, the bulletproofing section, the anti-patterns section).	2 / 3
	Total	7 / 12 Passed

Validation

90%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (656 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

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.