Use when creating new skills, editing existing skills, or verifying skills work before deployment
59
37%
Does it follow best practices?
Impact
100%
1.29xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/writing-skills/SKILL.mdQuality
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.
The description is essentially just a 'Use when...' trigger clause without any explanation of what the skill actually does. It lacks specificity about concrete actions (e.g., generating SKILL.md files, validating frontmatter, testing skill selection) and doesn't adequately define the domain of 'skills' for disambiguation purposes.
Suggestions
Add a 'what it does' clause before the trigger, e.g., 'Generates, edits, and validates SKILL.md files including YAML frontmatter, description fields, and markdown content.'
Include more specific trigger terms users would naturally say, such as 'SKILL.md', 'skill file', 'skill template', 'frontmatter', 'write a new skill', or 'test skill matching'.
Clarify what 'verifying skills work before deployment' means concretely, e.g., 'validates skill syntax, tests description quality, and checks for frontmatter errors'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what a 'skill' is, what creating one involves, or what verification entails. | 1 / 3 |
Completeness | The description functions as a 'Use when...' clause addressing when to use the skill, but it lacks a clear 'what does this do' component explaining the concrete capabilities or outputs of the skill. | 2 / 3 |
Trigger Term Quality | It includes some relevant keywords like 'skills', 'creating', 'editing', and 'deployment', but misses natural variations users might say such as 'SKILL.md', 'skill file', 'write a skill', 'test a skill', 'skill template', or 'frontmatter'. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'skills' provides some specificity to a niche domain, but 'creating', 'editing', and 'verifying' are generic enough that this could overlap with general file editing or testing skills. Without more detail about what skills are (e.g., markdown files, YAML frontmatter), the boundaries are unclear. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive but excessively verbose meta-skill about writing skills. Its greatest strength is the thorough coverage of CSO optimization, the concrete good/bad examples for YAML descriptions, and the structured checklist. Its greatest weakness is severe verbosity - it repeats core concepts (TDD mapping, Iron Law, no exceptions) multiple times, includes motivational content Claude doesn't need, and ironically violates its own token efficiency guidelines. The skill would benefit enormously from being cut to roughly 40% of its current length.
Suggestions
Cut the skill to under 500 words by removing repeated concepts (Iron Law appears 3+ times, TDD mapping is restated in multiple sections), the 8-row rationalization table, and motivational content Claude doesn't need.
Move the CSO section, bulletproofing/rationalization section, and testing-all-skill-types section to separate reference files, keeping only brief summaries with cross-references in the main SKILL.md.
Consolidate the workflow into a single clear sequence rather than scattering it across 'TDD Mapping', 'RED-GREEN-REFACTOR for Skills', 'The Iron Law', and 'Skill Creation Checklist' sections.
Add concrete validation criteria for the testing steps - what specific commands to run, what 'compliance' looks like, and how to determine when a skill is 'bulletproof' enough to deploy.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a skill is), repeats the same points multiple times (the Iron Law appears 3+ times, the TDD mapping is restated repeatedly), includes an 8-row rationalization table for skipping testing, and has extensive sections that could be dramatically compressed. The token efficiency section ironically violates its own advice. | 1 / 3 |
Actionability | The skill provides concrete YAML frontmatter examples, directory structures, and a detailed checklist, which are actionable. However, much of the content is philosophical/motivational rather than executable (e.g., the Iron Law repetitions, anti-pattern narratives). The actual skill creation steps are buried in verbose surrounding text, and the testing methodology defers to another file rather than providing concrete commands. | 2 / 3 |
Workflow Clarity | The RED-GREEN-REFACTOR workflow is clearly sequenced and the final checklist provides explicit steps. However, the validation steps are vague ('run scenarios WITH skill - verify agents now comply') without concrete commands or criteria for what 'comply' means. The workflow is also scattered across multiple sections rather than presented as one clear sequence, making it harder to follow. | 2 / 3 |
Progressive Disclosure | The skill references external files appropriately (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot) and correctly uses cross-references instead of @ links. However, the main SKILL.md itself is monolithic with too much inline content that could be split out - the CSO section, the bulletproofing section, and the testing section are each substantial enough to warrant separate files. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%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 | |
814cd52
Table of Contents
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.