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 serves only as a trigger clause ('Use when...') without explaining what the skill actually does. It lacks concrete actions, sufficient trigger terms, and enough specificity to clearly distinguish it from other skills. The domain of 'skills' is somewhat niche but the description needs substantially more detail about capabilities.

Suggestions

Add a 'what it does' component before the 'Use when' clause, e.g., 'Generates, edits, and validates SKILL.md files including YAML frontmatter, description fields, and markdown instruction content.'

Include more natural trigger terms and file references such as 'SKILL.md', 'skill file', 'skill template', 'frontmatter', 'skill definition', '.md skill format'.

Specify concrete actions like 'scaffolds skill files from templates', 'validates frontmatter schema', 'tests skill matching behavior' to improve specificity and distinctiveness.

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 is a comprehensive but excessively verbose skill that thoroughly covers skill creation methodology. Its main weakness is severe violation of its own conciseness principles - it's easily 3-5x longer than necessary, with repeated emphasis on the same TDD points, extensive rationalization tables, and explanations of concepts Claude already understands. The actionable content (YAML examples, directory structures, checklist) is good but buried in verbosity.

Suggestions

Reduce content by at least 60% - remove the TDD mapping table (Claude understands the analogy from one sentence), consolidate the 3+ repetitions of 'no skill without failing test', and cut the 8-row rationalization table to 2-3 key entries

Move the CSO section, testing methodology section, and bulletproofing section to separate reference files, keeping only 2-3 sentence summaries with links in the main SKILL.md

Add concrete, executable validation steps - e.g., a specific command or checklist to verify SKILL.md structure, frontmatter validity, and word count targets

Replace abstract testing descriptions with one complete, concrete example showing an actual pressure scenario, baseline result, skill written, and verification - rather than describing the process abstractly

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 has extensive sections that could be dramatically compressed. The token efficiency section ironically violates its own advice.	1 / 3
Actionability	The skill provides concrete YAML frontmatter examples, directory structures, and a detailed checklist, which are actionable. However, the actual skill creation process relies heavily on cross-referenced skills (test-driven-development, testing-skills-with-subagents) without providing the concrete testing commands or executable code. The 'how to test' is described abstractly rather than with copy-paste ready examples.	2 / 3
Workflow Clarity	The RED-GREEN-REFACTOR workflow is clearly sequenced and the final checklist provides good structure. However, validation checkpoints are implicit rather than explicit - there's no concrete verification step like 'run this command to validate your SKILL.md structure' or specific criteria for when a test has truly 'passed'. The checklist helps but lacks concrete validation commands.	2 / 3
Progressive Disclosure	The skill references external files appropriately (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot) and uses cross-referencing. However, the main SKILL.md itself is monolithic with too much inline content that could be split out - the CSO section, the testing section, and the bulletproofing section are each substantial enough to warrant separate files, making the main document overwhelming.	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: b7a8f76

Reviewed: about 2 hours 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.