writing-skills

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

Quality

72%

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

70%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.

A comprehensive, well-sequenced meta-skill with strong actionability and an explicit RED-GREEN-REFACTOR workflow including validation and feedback loops. Its main weaknesses are length/redundancy and heavy inlining of content that the referenced-file pattern it advocates would better serve.

Suggestions

Consolidate the description-format guidance into one location; it currently repeats across SKILL.md Structure, Skill Discovery Optimization, and Update SDO for Violation Symptoms.

Move the full SDO section and rationalization treatment into a separate reference file, keeping only the core principle and one example inline, to match the progressive-disclosure pattern the skill itself advocates.

Provide the referenced files (testing-skills-with-subagents.md, anthropic-best-practices.md, graphviz-conventions.dot, render-graphs.js, persuasion-principles.md) in references/scripts/ or trim the inline references to those that exist.

Dimension	Reasoning	Score
Conciseness	Mostly valuable expertise, but ~680 lines with noticeable redundancy: description-format guidance recurs in SKILL.md Structure, SDO, and Update SDO sections, and the rationalization table appears both as template and filled-in.	3 / 5
Actionability	Concrete copy-paste templates (YAML frontmatter, SKILL.md skeleton), specific commands (wc -w, render-graphs.js), word-count targets, and a detailed checklist; the core test-execution loop is deferred to a referenced file rather than shown inline.	4 / 5
Workflow Clarity	A clear RED-GREEN-REFACTOR sequence with explicit validation checkpoints (watch baseline fail, verify compliance, re-test until bulletproof), feedback loops, and a sequenced checklist — micro-test guidance adds concrete pass criteria (5+ reps, variance convergence).	5 / 5
Progressive Disclosure	References are clearly signaled and one-level-deep (testing-skills-with-subagents.md, anthropic-best-practices.md, etc.), but no bundle files exist and substantial sections (SDO, repeated example sets, rationalization treatment) are inlined that could be split into separate reference files.	3 / 5
	Total	15 / 20 Passed

Description

75%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 is concise, trigger-first, third-person, and names three concrete skill-authoring actions, giving it solid coverage across all dimensions. It sits just below top marks because it lacks a standalone declarative "what" sentence and a few natural synonyms.

Dimension	Reasoning	Score
Specificity	Names the domain and three concrete actions — "creating new skills", "editing existing skills", "verifying skills work" — with only minor coverage gaps (e.g., no mention of deleting/refactoring skills).	4 / 5
Completeness	Explicit "Use when..." trigger is present and the embedded verbs convey the "what", but there is no separate declarative statement of what the skill does as the 5-anchor example shows.	4 / 5
Trigger Term Quality	Phrases like "creating new skills", "editing existing skills", and "verifying skills work" are natural terms a user would say; a few synonyms (authoring, shipping, validating) are missing.	4 / 5
Distinctiveness Conflict Risk	Skill-authoring is a fairly distinct niche with clear triggers; minor overlap risk with general documentation or testing skills keeps it just below a 5.	4 / 5
	Total	16 / 20 Passed

Validation

87%

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

Validation for skill structure

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

	Total	14 / 16 Passed

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

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.