writing-skills

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

Install with Tessl CLI

npx tessl i github:obra/superpowers --skill writing-skills

What are skills?

Review — 58%

Does it follow best practices?

If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:

npx tessl skill review --optimize ./path/to/skill

Learn more

Validation — 10 / 11 Passed

Validation for skill structure

SKILL.md

Review

Evals

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.

This description focuses entirely on when to use the skill but completely omits what the skill actually does. While it correctly uses third person voice and includes a 'Use when' clause, the lack of concrete capabilities and specific actions makes it difficult for Claude to understand what this skill provides or how it differs from other editing/creation tools.

Suggestions

Add specific capabilities before the 'Use when' clause, e.g., 'Creates 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', 'new skill', 'skill syntax'

Clarify what 'skills' means in this context to improve distinctiveness, e.g., 'Claude skill definitions' or 'SKILL.md markdown files'

Dimension	Reasoning	Score
Specificity	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.	1 / 3
Completeness	The description provides a 'Use when...' clause addressing when to use it, but the 'what does this do' portion is entirely missing. There's no explanation of what capabilities the skill provides.	2 / 3
Trigger Term Quality	Contains some relevant keywords ('skills', 'deployment') but lacks natural variations users might say like 'skill file', 'SKILL.md', 'skill template', or 'test skill'. The term 'skills' is somewhat generic.	2 / 3
Distinctiveness Conflict Risk	The term 'skills' provides some specificity to this domain, but 'creating', 'editing', and 'verifying' are generic actions that could overlap with many other skills. Without more context about what skills are, conflict risk remains moderate.	2 / 3
	Total	7 / 12 Passed

Implementation

77%

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

This is a well-structured meta-skill with excellent actionability and workflow clarity, particularly strong in its TDD-adapted approach with explicit validation checkpoints. The main weakness is verbosity - at ~2500 words it exceeds the recommended <500 words guideline significantly, with some redundant content that could be consolidated or moved to supporting files.

Suggestions

Consolidate the TDD mapping table and repeated RED-GREEN-REFACTOR explanations into a single, concise section to reduce redundancy

Move the detailed 'Common Rationalizations for Skipping Testing' and 'Bulletproofing Skills Against Rationalization' sections to a supporting file like 'rationalization-defense.md' and reference it

Trim the CSO section examples - currently shows 6+ bad/good pairs when 2-3 would suffice to illustrate the pattern

Dimension	Reasoning	Score
Conciseness	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, much content is genuinely necessary for a meta-skill about creating skills.	2 / 3
Actionability	Provides concrete, executable guidance throughout: specific YAML frontmatter examples, directory structures, code examples for render-graphs.js, explicit checklists with TodoWrite instructions, and copy-paste ready templates for descriptions. The good/bad examples are particularly actionable.	3 / 3
Workflow Clarity	Excellent workflow clarity with explicit RED-GREEN-REFACTOR phases mapped to skill creation, clear validation checkpoints ('Run scenarios WITH skill - verify agents now comply'), and a comprehensive deployment checklist. The 'STOP: Before Moving to Next Skill' section explicitly prevents skipping validation.	3 / 3
Progressive Disclosure	References external files appropriately (testing-skills-with-subagents.md, persuasion-principles.md, graphviz-conventions.dot) 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.	2 / 3
	Total	10 / 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

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