writing-skills

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

Quality

56%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/writing-skills/SKILL.md

Quality

Content

56%Weight 40%Scale 1-5

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

The body delivers genuinely novel, highly actionable guidance (form-matching, micro-testing, rationalization tables) in a clear RED-GREEN-REFACTOR sequence, but it is noticeably verbose with systematic internal duplication and violates its own token-efficiency targets. Referenced companion files are absent from the bundle, breaking progressive disclosure.

Suggestions

Deduplicate repeated guidance: description rules, naming conventions, and frontmatter requirements each appear 2-3 times across 'SKILL.md Structure', 'Skill Discovery Optimization', and the checklist — consolidate each into one canonical section.

Actually include the referenced bundle files (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, render-graphs.js, graphviz-conventions.dot) or remove the references, since every 'in this directory' pointer currently resolves to nothing.

Move the long example blocks (SDO good/bad examples, file-organization walkthroughs) into the referenced detail files to bring the body closer to its own stated token targets.

Dimension	Reasoning	Score
Conciseness	The body (~680 lines, roughly 8x its own stated <500-word target for skills) systematically duplicates guidance: description rules appear in 'SKILL.md Structure', 'Skill Discovery Optimization', and the checklist; naming guidance repeats under SDO sections 3 and 4; and the delete-the-code rule appears in both the Iron Law and the bulletproofing example. This matches the 'noticeably verbose; several unnecessary explanations or padded sections' anchor rather than the mostly-efficient level 3.	2 / 5
Actionability	Concrete, executable guidance throughout — 'wc -w skills/path/SKILL.md', 'node ./render-graphs.js ../some-skill --combine', 'bash scripts/tool.sh' invocation rules, before/after description examples, and filled-in checklists. It falls short of level 5 because the core 'run pressure scenario with subagent' mechanics are deferred to a referenced file rather than shown with a concrete invocation.	4 / 5
Workflow Clarity	The RED-GREEN-REFACTOR cycle is clearly sequenced with explicit validation checkpoints (run baseline without skill, verify compliance with skill, re-test until bulletproof), numbered micro-test steps, and a per-phase creation checklist. The minor gap keeping it from level 5 is that the scenario-execution mechanics live in a referenced external file rather than inline.	4 / 5
Progressive Disclosure	References are one level deep and clearly signaled ('See testing-skills-with-subagents.md', 'anthropic-best-practices.md', 'render-graphs.js in this directory'), but the bundle contains no reference, script, or asset directories — none of the five files referenced as being 'in this directory' exist, so navigation breaks at every reference point. This fits the 'some structure but could be better organized' anchor rather than level 4's 'references mostly clear'.	3 / 5
	Total	13 / 20 Passed

Description

57%Weight 40%Scale 1-5

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 follows its own 'Use when...' trigger convention with concrete, natural phrasing and a distinct niche, but it omits any 'what' statement, leaving an agent unable to distinguish what this skill does versus a sibling skill. This is the one dimension holding it back from a strong score.

Suggestions

Add a brief 'what' clause before the trigger, e.g., 'Test-driven development for skill documentation: baseline-test agents, write the skill, verify compliance. Use when creating new skills, editing existing skills, or verifying skills work before deployment.'

Include additional natural trigger terms users might say, such as 'authoring skills', 'SKILL.md', 'frontmatter', or 'skill not triggering', to broaden keyword coverage.

Mention the testing angle explicitly (e.g., 'pressure-testing skills with subagents') so it is distinguishable from generic writing/editing skills.

Dimension	Reasoning	Score
Specificity	The description names the domain and three concrete actions — 'creating new skills, editing existing skills, or verifying skills work before deployment' — with only minor gaps, matching the anchor for several specific actions rather than the 1-2 actions of level 3.	4 / 5
Completeness	It has an explicit, well-formed 'Use when...' clause but contains no statement of what the skill actually does (e.g., TDD-based skill testing with subagents), matching the anchor where only 'when' is present without 'what'.	2 / 5
Trigger Term Quality	'Creating new skills', 'editing existing skills', and 'verifying skills work' are natural phrases users would say, giving good keyword coverage, though common synonyms like 'authoring', 'SKILL.md', or 'frontmatter' are missing, so it falls short of comprehensive level 5.	4 / 5
Distinctiveness Conflict Risk	The skill-authoring niche is clear and triggers are specific, with only minor overlap risk against closely related skills like testing or writing skills, fitting the 'mostly distinct' anchor.	4 / 5
	Total	14 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (682 lines); consider splitting into references/ and linking	Warning
relative_links	Relative link issues: 1 missing, 2 suspicious	Warning
referenced_paths_exist	Referenced path issues: 3 missing	Warning

	Total	13 / 16 Passed

Repository: obra/superpowers
Path: skills/writing-skills/SKILL.md
Commit: 8ca22db

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