CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

writing-skills

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

Quality

68%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/writing-skills/SKILL.md
SKILL.md
Quality
Evals
Security

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.

A well-structured, genuinely actionable process guide with a clear RED-GREEN-REFACTOR workflow, explicit validation checkpoints, and concrete templates and checklists. Its two real weaknesses are verbosity — extensive duplication of description guidance, the TDD cycle, and the Iron Law pushes it far past its own token targets — and broken progressive disclosure: all five referenced bundle files are missing, including the one containing the core testing methodology.

Suggestions

Consolidate duplicated material: merge the description-writing guidance and good/bad YAML examples from 'SKILL.md Structure' and 'Claude Search Optimization' into one section, fold the TDD Mapping table into the RED-GREEN-REFACTOR section, and state the Iron Law once — this alone would cut roughly a third of the body's tokens.

Ship the referenced bundle files (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot, render-graphs.js) or inline/remove their references — currently every external link, including the core testing methodology, is a dead end.

Apply the skill's own rules to itself: replace '@testing-skills-with-subagents.md' and '@graphviz-conventions.dot' with plain named references (per 'Why no @ links'), and move the 100+ line CSO and testing-type sections into separate reference files as its 'Separate files for heavy reference' rule requires.

DimensionReasoningScore

Conciseness

At 3,308 words / 666 lines the body is over six times its own stated target ('Other skills: <500 words'), with several duplicated sections: description-writing guidance and good/bad YAML examples appear twice (SKILL.md Structure vs. Claude Search Optimization), the RED-GREEN-REFACTOR cycle is covered by both the TDD Mapping table and its own dedicated section, the Iron Law appears in both 'The Iron Law' and 'The Bottom Line', and the rationalization table is given twice (filled example plus template). This matches the anchor for noticeably verbose with several unnecessary or padded sections; it avoids a 1 because the material is domain-specific expert content rather than explanations of concepts Claude already knows.

2 / 5

Actionability

The body provides mostly concrete, executable guidance: a filled-in YAML frontmatter template, explicit good/bad description examples, runnable commands ('wc -w skills/path/SKILL.md', './render-graphs.js ../some-skill --combine'), a Bad/Good counter-example pair, and a phase-organized checklist with a TodoWrite instruction. It is not a 5 because key operational detail — 'How to write pressure scenarios', 'Pressure types (time, sunk cost, authority, exhaustion)' — is deferred to testing-skills-with-subagents.md, which is not present in the bundle, so the RED phase cannot be fully executed from what is provided.

4 / 5

Workflow Clarity

The RED-GREEN-REFACTOR sequence is clearly laid out with explicit checkpoints ('Run pressure scenario with subagent WITHOUT the skill. Document exact behavior', 'Run same scenarios WITH skill. Agent should now comply'), a feedback loop ('Agent found new rationalization? Add explicit counter. Re-test until bulletproof'), a phase-organized checklist, and a hard gate ('STOP: Before Moving to Next Skill'). It falls short of the 5 anchor because the actual scenario-construction methodology behind the validation steps lives in the missing @testing-skills-with-subagents.md file, leaving a gap in how validation is performed.

4 / 5

Progressive Disclosure

The body has clear ## section structure, but all five referenced supporting files — anthropic-best-practices.md, graphviz-conventions.dot, render-graphs.js, persuasion-principles.md, and testing-skills-with-subagents.md — are absent from the bundle (no references/, scripts/, or assets/ directories exist), so every external reference is a dead end, including the one holding the 'complete testing methodology'. Additionally, 600+ lines of CSO guidance and testing-approach content are inlined where the skill's own rule ('Separate files for: Heavy reference (100+ lines)') says they belong in separate files, and it uses @-references ('@graphviz-conventions.dot', '@testing-skills-with-subagents.md') that its own guidance forbids. This sits between the 'references are buried/inlined content' anchor (2) and the 'good structure, some organization gaps' anchor (4): structure is genuinely good but navigation is broken, so 3 is the best fit.

3 / 5

Total

13

/

20

Passed

Description

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

A lean, trigger-focused description with explicit 'Use when' guidance covering the three main skill-lifecycle activities, good natural keyword choice, and a clear niche. Its main weakness is that it answers only 'when' — the description never conveys what the skill actually provides, and it lacks common synonyms like 'writing' or 'testing' skills.

Suggestions

Add a brief 'what' clause alongside the triggers (e.g., 'Provides a test-driven workflow for authoring and validating agent skills. Use when creating new skills, editing existing skills, or verifying skills work before deployment.') so the description answers both what and when.

Include natural synonym triggers users and Claude would search for — 'writing skills', 'testing skills', 'skill authoring', 'SKILL.md frontmatter' — to broaden keyword coverage.

Clarify the domain in the trigger (agent/Claude skills rather than human writing skills) to further reduce overlap risk with general writing or testing skills.

DimensionReasoningScore

Specificity

The description lists three parallel concrete actions — "creating new skills", "editing existing skills", "verifying skills work before deployment" — matching the anchor for several specific actions with minor gaps in coverage. It is not a 5 because the actions are high-level lifecycle verbs with no finer-grained capabilities mentioned, and not a 3 because three distinct triggering actions exceed the '1-2 concrete actions' of that anchor.

4 / 5

Completeness

The entire description is a single trigger clause ("Use when creating... editing... verifying...") that answers 'when' explicitly and thoroughly, but 'what the skill does' is entirely absent — it never states it provides a TDD-based authoring/testing process. This matches anchor 2's condition (only 'when' present without 'what') but with a far more explicit 'when' than that anchor's vague example, making it equivalent in completeness to anchor 3's mirror case (clear what, missing when); it cannot be 4 since anchor 4 requires both what and when.

3 / 5

Trigger Term Quality

Phrases like "creating new skills", "editing existing skills", and "verifying skills work before deployment" are natural things a user would say when needing this skill, giving good keyword coverage. It falls short of the 5 anchor because common synonyms and variations are missing — "writing skills", "testing skills", "skill authoring", or "SKILL.md" — while still exceeding the 'some relevant keywords' bar of a 3.

4 / 5

Distinctiveness Conflict Risk

The skill-authoring niche is clear and the triggers ("creating new skills", "verifying skills work before deployment") are domain-specific with only minor overlap risk against closely related testing/deployment or documentation skills. It is not a 5 because "verifying skills work" and "editing" could still collide with generic testing or editing skills.

4 / 5

Total

15

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

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

Warning

Total

15

/

16

Passed

Repository

lucianghinda/superpowers-ruby

Path

skills/writing-skills/SKILL.md

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.