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 functions primarily as a 'when to use' clause but lacks any explanation of what the skill actually does—it doesn't describe concrete capabilities like generating skill YAML frontmatter, validating skill structure, or creating markdown templates. The trigger terms are somewhat relevant but miss natural user phrasings, and the vague action words reduce distinctiveness.
Suggestions
Add a 'what it does' clause listing specific actions, e.g., 'Generates skill markdown files with proper YAML frontmatter, validates skill structure, and creates templates for new skills.'
Include more natural trigger terms users might say, such as 'SKILL.md', 'skill file', 'skill template', 'write a skill', or 'skill format'.
Improve distinctiveness by specifying the skill file format and domain, e.g., 'Works with SKILL.md files including frontmatter fields like description, triggers, and instructions.'
| 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 addresses 'when' (creating, editing, verifying skills) but lacks a clear 'what does this do' component. There's no explanation of the actual capabilities or actions the skill performs. | 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', or 'skill template'. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'skills' provides some specificity to a niche domain, but 'creating', 'editing', and 'verifying' are generic enough that they could overlap with general file editing or testing skills. | 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 skill attempts to be a comprehensive guide to skill creation using a TDD metaphor, but suffers significantly from verbosity and repetition. The same core message ('test before writing') is restated in at least 5 different ways, rationalization tables are extensive but redundant, and concepts Claude already understands (TDD basics, file organization) are over-explained. The structure and intent are sound, but the execution violates the skill's own token efficiency guidelines.
Suggestions
Cut content by at least 50% - remove redundant restatements of the Iron Law, compress the rationalization table to 3-4 entries max, and eliminate explanations of concepts Claude already knows (what TDD is, what a skill is, basic file organization patterns).
Add concrete, executable examples for the core workflow: show an actual subagent invocation command for baseline testing, a real pressure scenario prompt, and a specific verification command to confirm skill compliance.
Split the monolithic content: move the CSO section, rationalization/bulletproofing guidance, and testing-by-skill-type sections into separate referenced files, keeping SKILL.md as a concise overview with the checklist and core workflow.
Add explicit validation checkpoints: include a concrete command or method to verify YAML frontmatter validity, a word count check step, and a specific 'how to confirm the test passed' criterion rather than the abstract 'agent now complies'.
| 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, basic file organization), includes extensive rationalization tables, repeats the same points multiple times ('Iron Law' stated 3+ times), and contains lengthy anti-pattern explanations. The CSO section alone could be cut by 60%. Much content is redundant with the referenced test-driven-development skill. | 1 / 3 |
Actionability | The skill provides concrete YAML frontmatter examples, directory structures, and a detailed checklist. However, it lacks executable code for the core workflow (no actual subagent invocation commands, no concrete test scenario examples that are copy-paste ready). The testing methodology is described abstractly rather than with runnable examples, and the actual 'how to run a pressure scenario' is deferred to another file. | 2 / 3 |
Workflow Clarity | The RED-GREEN-REFACTOR cycle is clearly mapped to skill creation, and the checklist at the end provides a good sequence. However, validation checkpoints are weak - there's no concrete verification step (e.g., how to confirm a skill 'passes'), no specific commands to validate YAML frontmatter, and the testing methodology is entirely deferred to another file. The workflow for actually running baseline tests vs. skill-present tests lacks concrete steps. | 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) which suggests good intent for progressive disclosure. However, no bundle files are provided, so we can't verify these exist. The main SKILL.md itself is monolithic - the CSO section, rationalization tables, and testing guidance could be split into separate reference files. The inline content is far too long for what should be an overview. | 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 | |
0d67646
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.