CtrlK
BlogDocsLog inGet started
Tessl Logo

writing-skills

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

66

Quality

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

Quality

Content

77%

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

The body delivers highly actionable, well-sequenced TDD-for-skills guidance with strong validation checkpoints and concrete templates. Its weaknesses are verbosity from repeated rules and a monolithic structure that references external files which are not actually present in the bundle.

Suggestions

De-duplicate the description-guidance rule: state the "NEVER summarize workflow in description" principle once in the SDO section and cross-reference it elsewhere instead of restating it multiple times.

Move the testing methodology and bulletproofing toolkit into the referenced files (testing-skills-with-subagents.md, persuasion-principles.md) and include those files in a references/ or scripts/ bundle so the one-level-deep links resolve.

Trim restated framing (e.g., repeated "creating skills IS TDD" declarations) to bring the body closer to the stated token-efficiency targets for frequently-loaded skills.

DimensionReasoningScore

Conciseness

The ~690-line body is mostly substantive skill-authoring craft Claude would not already know, but it repeats the "NEVER summarize workflow in description" rule across several sections and re-asserts "creating skills IS TDD" multiple times, fitting the level-2 anchor of mostly efficient with some unnecessary explanation that could be tightened; not level 3 because repetition means not every token earns its place, not level 1 because it avoids explaining generic concepts Claude already knows.

2 / 3

Actionability

Concrete, copy-paste-ready guidance pervades the body: directory-structure templates, frontmatter YAML format, specific word-count targets, `wc -w skills/path/SKILL.md` verification commands, the TDD mapping table, and a per-phase checklist, matching the level-3 anchor of specific executable guidance; illustrative YAML/markdown templates are appropriate for an instruction/process skill rather than penalized.

3 / 3

Workflow Clarity

The RED-GREEN-REFACTOR cycle is explicitly sequenced (baseline failing test → write minimal skill → close loopholes) with validation checkpoints ("Run scenarios WITH skill - verify agents now comply", "Re-test until bulletproof", the micro-test control requirement) and the "STOP" gate, matching the level-3 anchor of clear sequence with explicit validation and feedback loops.

3 / 3

Progressive Disclosure

The body references several one-level-deep files (anthropic-best-practices.md, testing-skills-with-subagents.md, graphviz-conventions.dot, render-graphs.js, persuasion-principles.md) but no references/, scripts/, or assets/ bundle directories exist, so those paths are dangling, and the monolithic ~690-line body keeps content that could be split (testing methodology, bulletproofing toolkit) inline, fitting the level-2 anchor; not level 1 because references are clearly signaled and not deeply nested, not level 3 because referenced files are absent from the bundle and large sections remain inline.

2 / 3

Total

10

/

12

Passed

Description

85%

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 third-person, trigger-focused, and names three concrete actions with an explicit "Use when" clause, giving strong completeness, specificity, and distinctiveness. Its main weakness is limited keyword variation—one phrasing per use case rather than a broad set of synonyms a user might actually say.

Suggestions

Broaden trigger keyword coverage with synonyms and natural phrasings users might say (e.g., "authoring skills", "skill documentation", "skill quality checks", "SKILL.md") so each use case has multiple natural search terms.

Consider adding symptom-oriented triggers that signal the skill applies even when the user doesn't literally say "create a skill" (e.g., "when a skill isn't being followed by agents", "when skill descriptions trigger the wrong behavior").

DimensionReasoningScore

Specificity

"creating new skills, editing existing skills, or verifying skills work before deployment" lists three distinct concrete actions, matching the level-3 anchor that expects multiple specific concrete actions rather than a single vague domain mention.

3 / 3

Completeness

The explicit "Use when..." clause answers when to use it, and the three actions double as what it does, satisfying the level-3 anchor of clearly answering both what and when with explicit triggers; it is not level 2 because the trigger guidance is explicit, not merely implied.

3 / 3

Trigger Term Quality

The phrases ("creating new skills", "editing existing skills", "verifying skills work") are natural, but each use case has only one phrasing with no synonyms or common variations, fitting the level-2 anchor of relevant keywords missing common variations rather than the broad coverage of level 3.

2 / 3

Distinctiveness Conflict Risk

"creating new skills, editing existing skills, or verifying skills work before deployment" carves a clear skill-authoring niche with distinct triggers unlikely to overlap with unrelated skills, matching the level-3 anchor.

3 / 3

Total

11

/

12

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (690 lines); consider splitting into references/ and linking

Warning

relative_links

Relative link issues: 1 missing

Warning

Total

14

/

16

Passed

Repository
obra/superpowers
Reviewed

Table of Contents

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.