writing-skills

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

Quality

37%

Does it follow best practices?

Impact

Pending

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 provides reasonable trigger guidance via its 'Use when...' clause but critically lacks any explanation of what the skill actually does—it only says when to use it, not what capabilities it offers. The language is too vague to help Claude distinguish this skill's concrete actions from other editing or creation-related skills.

Suggestions

Add a 'what it does' clause before the 'Use when' clause, listing specific actions like 'Generates SKILL.md files with proper YAML frontmatter, validates skill structure, and provides templates for new skills.'

Include more natural trigger terms users might say, such as 'SKILL.md', 'skill file', 'skill template', 'write a skill', 'test skill', or 'skill format'.

Add specificity about what 'verifying skills work' means—e.g., 'validates frontmatter fields, checks description quality, and tests skill file syntax'.

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 provides a 'when' clause ('Use when creating new skills, editing existing skills, or verifying skills work before deployment') but lacks a clear 'what does this do' component explaining the actual capabilities or actions the skill performs.	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' is somewhat specific to a particular domain (skill file management), but without more concrete details, it could overlap with general file editing or template creation skills.	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 is comprehensive and covers skill creation thoroughly, but severely violates its own token efficiency principles—it's one of the most verbose skills imaginable while containing a section about keeping skills under 200-500 words. The core workflow (RED-GREEN-REFACTOR for skills) is sound but is repeated and restated so many times across different sections that the signal-to-noise ratio suffers. The content would benefit enormously from practicing what it preaches about conciseness.

Suggestions

Reduce content by 60-70% by eliminating repeated concepts (the Iron Law, TDD mapping, and RED-GREEN-REFACTOR cycle are each stated 3+ times) and removing explanations of concepts Claude already knows (what TDD is, what skills are, why testing matters).

Move the CSO section, bulletproofing/rationalization content, and testing-by-skill-type sections into separate reference files, keeping only a brief summary and cross-reference in the main SKILL.md.

Consolidate the workflow into a single clear sequence (the checklist at the end) and remove the redundant TDD Mapping table, Iron Law section, and separate RED-GREEN-REFACTOR section.

Add concrete, executable validation commands for testing skills (e.g., specific subagent dispatch commands, word count verification commands) rather than abstract instructions like 'verify agents now comply'.

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), repeats the same points multiple times (the Iron Law appears 3+ times, the TDD mapping is restated repeatedly), includes an 8-row rationalization table for skipping testing, and contains extensive anti-pattern examples. The token efficiency section ironically exists in one of the most token-heavy skills possible.	1 / 3
Actionability	The skill provides concrete YAML frontmatter examples, directory structures, and a detailed checklist, which are actionable. However, much of the content is philosophical/motivational rather than executable (e.g., the Iron Law section, rationalization tables, persuasion psychology references). The actual skill creation steps are buried in verbose surrounding material, and the testing methodology defers to an external file rather than providing concrete commands.	2 / 3
Workflow Clarity	The RED-GREEN-REFACTOR workflow is clearly sequenced and the final checklist provides explicit steps. However, the validation steps are vague ('run scenarios WITH skill - verify agents now comply') without concrete commands or criteria for what passing looks like. The workflow is also scattered across multiple sections (TDD Mapping, Iron Law, RED-GREEN-REFACTOR, Checklist) rather than presented as one clear sequence.	2 / 3
Progressive Disclosure	The skill references external files appropriately (testing-skills-with-subagents.md, persuasion-principles.md, graphviz-conventions.dot, anthropic-best-practices.md) and uses cross-referencing. However, the main SKILL.md itself is monolithic with too much inline content that could be split out (the entire CSO section, the bulletproofing section, the testing all skill types section). The structure has many sections but they overlap significantly.	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: 6efe32c

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