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 provides reasonable 'when to use' guidance but almost entirely lacks a 'what it does' component — it doesn't describe any concrete capabilities like generating YAML frontmatter, validating skill structure, or creating markdown templates. The trigger terms are moderately useful but could be more specific to the skill file format and ecosystem.
Suggestions
Add concrete capability descriptions before the 'Use when' clause, e.g., 'Generates skill markdown files with proper YAML frontmatter, validates skill structure, and tests skill behavior.'
Expand trigger terms to include format-specific keywords like 'SKILL.md', 'skill file', 'skill template', 'frontmatter', or 'skill definition'.
Clarify what 'verifying skills work before deployment' actually entails — does it run tests, validate syntax, check for required fields?
| 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 answers 'when' with explicit trigger conditions ('Use when creating new skills, editing existing skills, or verifying skills'), but the 'what does this do' part is essentially absent — it only restates the triggers without describing the actual capabilities or actions the skill performs. | 2 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'skills', 'creating new skills', 'editing existing skills', and 'deployment' that users might naturally say. However, it misses variations like 'skill.md', 'SKILL file', 'skill template', 'skill frontmatter', or 'skill testing'. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'skills' provides some specificity to a niche domain, but without clarifying what kind of skills (e.g., SKILL.md files, Claude skills), it could overlap with general coding or documentation skills. The word 'deployment' is also quite generic. | 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 the TDD-for-documentation concept, CSO optimization, and the detailed checklist. Its greatest weakness is that it violates its own principles—it advocates for token efficiency and conciseness while being extremely long and repetitive, and it advocates for testing-first while providing no concrete, executable test examples. The skill would benefit enormously from practicing what it preaches: compressing to ~500 words with heavy reference material in separate files.
Suggestions
Reduce the main SKILL.md to under 500 words (as the skill itself recommends) by moving the rationalization tables, anti-patterns, CSO details, and testing methodology into separate reference files (e.g., cso-guide.md, rationalization-patterns.md, testing-guide.md)
Add a concrete, executable example of running a baseline test with a subagent—show the actual command/prompt used, the expected failing output, and what 'passing' looks like, rather than describing the concept abstractly
Remove redundant explanations: the TDD mapping table, the prose explanation of TDD, and the 'Bottom Line' section all say the same thing three times—pick one representation
Add explicit validation commands to the checklist (e.g., 'wc -w SKILL.md' to verify word count, a concrete subagent invocation template) to match the workflow_clarity standards the skill itself defines
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a PDF is metaphorically, basic rationalization psychology), repeats the same points multiple times (the Iron Law appears twice, the 'no exceptions' pattern repeats, the TDD mapping table duplicates the prose explanation), and includes extensive rationalization tables and anti-pattern sections that could be dramatically compressed. The irony is that the skill itself advocates for token efficiency (<500 words for most skills) while massively exceeding that target. | 1 / 3 |
Actionability | The skill provides some concrete guidance (YAML frontmatter examples, directory structure, naming conventions, checklist items) but lacks executable code for the core workflow. The testing methodology references an external file (@testing-skills-with-subagents.md) rather than providing concrete test commands. The 'how to actually run a baseline test with a subagent' is never shown with a concrete, copy-paste-ready example—it stays at the conceptual level. | 2 / 3 |
Workflow Clarity | The RED-GREEN-REFACTOR cycle is clearly sequenced and the final checklist provides good structure. However, validation checkpoints are implicit rather than explicit—there's no concrete 'run this command to verify' step. The checklist says 'Run scenarios WITH skill - verify agents now comply' but doesn't specify how to verify compliance or what passing looks like. For a skill about testing/verification, the absence of concrete validation commands is a notable gap. | 2 / 3 |
Progressive Disclosure | The skill references several external files (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot, render-graphs.js) which suggests good intent for progressive disclosure. However, no bundle files were provided, so we can't verify these references resolve. The main SKILL.md itself is monolithic—much of the content (rationalization tables, anti-patterns, CSO details, flowchart usage) could be split into separate reference files, following the skill's own advice about keeping frequently-loaded skills under 500 words. | 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 | |
76a5a21
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.