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

Content

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 contains valuable concepts (TDD mapping, CSO optimization, rationalization tables) but buries them in repetitive explanations and sections that could be separate reference files. The irony of a 2500+ word skill that advises '<500 words' and '<150 words for frequently-loaded skills' significantly undermines its credibility and utility.

Suggestions

Reduce the SKILL.md to under 500 words by moving the CSO section, bulletproofing/rationalization guidance, testing methodology, and anti-patterns into separate referenced files (e.g., cso-guide.md, testing-skills.md, anti-patterns.md)

Remove explanations of what TDD is and how it maps to skills—Claude knows TDD. Replace the mapping table with a single sentence: 'Apply RED-GREEN-REFACTOR: baseline test without skill → write minimal skill → close loopholes'

Add concrete, executable examples of the core workflow: show an actual pressure scenario prompt, an actual baseline result, and the resulting skill content, rather than abstract descriptions

Eliminate redundancy: the 'Iron Law' is stated 3+ times, the 'no exceptions' pattern appears twice with similar lists, and the 'description should not summarize workflow' point is made 4 separate times with examples

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 contains 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, validation checkpoints are vague ('run scenarios WITH skill - verify agents now comply') without specifying how to verify compliance. The testing methodology is deferred to an external file (testing-skills-with-subagents.md), leaving gaps in the actual workflow.	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) but none are provided in the bundle. The main SKILL.md contains far too much inline content that could be split out (the entire CSO section, the rationalization/bulletproofing section, the anti-patterns section). The structure has good headers but the content is monolithic.	2 / 3
	Total	7 / 12 Passed

Description

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 and lacks concrete actions or specific terminology that would help Claude confidently select this skill over others. It needs both a capability summary and more specific trigger terms.

Suggestions

Add a 'what' clause before the 'Use when' that describes concrete actions, e.g., 'Generates SKILL.md files with proper YAML frontmatter, markdown structure, and validation. Use when...'

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

Clarify what 'verifying skills work before deployment' means concretely, e.g., 'validates frontmatter schema, checks for required fields, and tests skill formatting'

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

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: 6fd4507

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