writing-skills

Name: writing-skills
Rating: 68 (1 reviews)
Author: obra

tessl install github:obra/superpowers --skill writing-skills

github.com/obra/superpowers

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

Review Score

68%

Validation Score

13/16

Implementation Score

77%

Activation Score

40%

SKILL.md

Review

Evals

Generated

13 days ago

Warnings & errors only

Criteria	Score
skill_md_line_count	SKILL.md is long (656 lines); consider splitting into references/ and linking
metadata_version	'metadata' field is not a dictionary
license_field	'license' field is missing

Overall Assessment

This is a well-structured, highly actionable skill that successfully adapts TDD principles to documentation creation. Its main strength is the concrete, executable guidance with clear workflows and validation checkpoints. The primary weakness is verbosity - at ~2500 words it exceeds recommended limits and contains some redundancy that could be trimmed without losing clarity.

Suggestions

Reduce word count by consolidating redundant sections (TDD mapping appears in overview, table, and bottom line; rationalization content appears twice)
Move the detailed 'Testing All Skill Types' and 'Common Rationalizations' sections to a separate testing-skills-reference.md file, keeping only summaries inline
Compress the anti-patterns section into a simple table format rather than individual headers with explanations

Dimension	Score	Reasoning
Conciseness	2/3	The skill is comprehensive but verbose at ~2500 words. Contains some redundancy (TDD mapping repeated multiple times, rationalization tables appear twice) and explanatory content that could be trimmed. However, most content earns its place given the complexity of the topic.
Actionability	3/3	Provides concrete, executable guidance throughout: specific directory structures, YAML frontmatter examples, code blocks for file organization, complete checklists with TodoWrite instruction, and copy-paste ready templates. The good/bad examples are particularly actionable.
Workflow Clarity	3/3	Excellent workflow clarity with explicit RED-GREEN-REFACTOR phases mapped to skill creation, detailed checklists with validation checkpoints, and clear 'STOP' gates before moving to next skill. The deployment checklist enforces verification at each phase.
Progressive Disclosure	2/3	References external files appropriately (testing-skills-with-subagents.md, persuasion-principles.md, anthropic-best-practices.md) but the main document is quite long. Some sections like the rationalization tables and anti-patterns could potentially be moved to supporting files. The structure is good but content density is high.

Overall Assessment

This description focuses entirely on when to use the skill but completely omits what the skill actually does. While it provides trigger conditions, the lack of concrete capabilities makes it difficult for Claude to understand the skill's purpose or distinguish it from other development-related skills.

Suggestions

Add specific capabilities before the 'Use when' clause, such as 'Generates SKILL.md files with proper YAML frontmatter, validates skill syntax, and tests skill behavior'
Include more natural trigger terms users might say: 'skill file', 'SKILL.md', 'skill template', 'write a skill', 'skill syntax'
Clarify what 'verifying skills work' means with concrete actions like 'validates YAML structure, checks required fields, tests skill matching'

Dimension	Score	Reasoning
Specificity	1/3	The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what skills are, what creating/editing involves, or what verification entails.
Completeness	2/3	Has a 'Use when...' clause addressing when to use it, but the 'what does this do' portion is entirely missing. The description only specifies triggers without explaining capabilities.
Trigger Term Quality	2/3	Contains some relevant keywords ('skills', 'deployment') but misses common variations users might say like 'SKILL.md', 'skill file', 'skill template', or 'test skill'. The term 'skills' is somewhat generic.
Distinctiveness Conflict Risk	2/3	The term 'skills' provides some specificity to this domain, but 'creating', 'editing', and 'verifying' are generic actions that could overlap with other development or documentation skills.