writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
69
62%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./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.
This description focuses entirely on when to use the skill but completely omits what the skill actually does. While it correctly uses third person voice and includes a 'Use when...' clause, the lack of concrete capabilities and specific trigger terms makes it difficult for Claude to understand the skill's purpose or distinguish it from other skills.
Suggestions
Add specific capabilities before the 'Use when...' clause, e.g., 'Generates skill markdown files with proper YAML frontmatter, validates skill syntax, and tests skill behavior.'
Include more natural trigger terms users would say, such as 'SKILL.md', 'skill file', 'skill template', 'write a skill', or 'new skill'.
Clarify what 'verifying skills work' means with concrete actions like 'validates YAML structure', 'checks required fields', or 'runs skill tests'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what skills are, what creating/editing involves, or what verification entails. | 1 / 3 |
Completeness | The description provides a 'Use when...' clause addressing when to use it, but the 'what does this do' portion is entirely missing. There's no explanation of what capabilities or actions the skill provides. | 2 / 3 |
Trigger Term Quality | Contains some relevant keywords ('skills', 'deployment') but misses natural variations users might say like 'skill file', 'SKILL.md', 'skill template', or 'test skill'. The term 'skills' is somewhat generic. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'skills' provides some specificity to this domain, but 'creating', 'editing', and 'verifying' are generic actions that could overlap with many other skills. Without more specific triggers, it could conflict with general editing or testing skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, highly actionable skill that effectively teaches skill creation through a TDD lens. Its main weakness is verbosity—at ~2500 words it exceeds the recommended <500 word target significantly, with some redundant explanations of TDD concepts. The workflow clarity and progressive disclosure are excellent, with clear checkpoints and appropriate cross-referencing.
Suggestions
Reduce word count by 40-50%: consolidate the multiple TDD explanations into one section, remove redundant 'Iron Law' restatements, and compress the anti-patterns section into a table
Move the detailed 'Testing All Skill Types' and 'Bulletproofing Skills Against Rationalization' sections to separate reference files, keeping only summaries in SKILL.md
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but verbose at ~2500 words. It includes some redundant explanations (e.g., TDD concepts explained multiple times) and sections that could be condensed. However, most content is actionable rather than explaining concepts Claude already knows. | 2 / 3 |
Actionability | Provides concrete, executable guidance throughout: specific directory structures, YAML frontmatter examples, code blocks, checklists with checkboxes, and clear good/bad examples. The rationalization tables and red flags lists are immediately usable. | 3 / 3 |
Workflow Clarity | Excellent workflow clarity with explicit RED-GREEN-REFACTOR phases, validation checkpoints ('STOP: Before Moving to Next Skill'), and a comprehensive checklist with TodoWrite instruction. The TDD mapping table clearly sequences the process with feedback loops. | 3 / 3 |
Progressive Disclosure | Well-structured with clear sections, appropriate cross-references to other skills (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md), and explicit guidance on when to inline vs. link to separate files. References are one level deep and clearly signaled. | 3 / 3 |
Total | 11 / 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 | |
- Repository
- roman01la/skills-agents
- Commit
45417f2
- 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.