agent-specification
Agent skill for specification - invoke with $agent-specification
35
13%
Does it follow best practices?
Impact
51%
1.54xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/agent-specification/SKILL.mdQuality
Discovery
0%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 is an extremely weak description that provides virtually no useful information for skill selection. It fails on all dimensions — it doesn't describe what the skill does, when to use it, or include any natural trigger terms. It reads more like a label than a functional description.
Suggestions
Describe the concrete actions this skill performs (e.g., 'Generates software specification documents from requirements', 'Reviews and validates technical specifications').
Add an explicit 'Use when...' clause with natural trigger terms users would say (e.g., 'Use when the user asks to create, review, or edit a specification, requirements document, or technical spec').
Specify the type of specification (software, API, product, etc.) to reduce conflict risk with other skills and make the description distinctive.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description provides no concrete actions whatsoever. 'Agent skill for specification' is extremely vague — it doesn't describe what kind of specification, what actions are performed, or what outputs are produced. | 1 / 3 |
Completeness | Neither 'what does this do' nor 'when should Claude use it' is answered. There is no 'Use when...' clause and no meaningful description of functionality. | 1 / 3 |
Trigger Term Quality | The only potentially relevant keyword is 'specification', which is overly generic. There are no natural terms a user would say, and '$agent-specification' is an invocation command, not a trigger term. | 1 / 3 |
Distinctiveness Conflict Risk | The term 'specification' is extremely broad and could overlap with any skill involving specs, requirements, documentation, or design. There is nothing to distinguish this skill from others. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is excessively verbose, containing generic specification templates and explanations of concepts Claude already understands well (requirements gathering, use cases, acceptance criteria). The content reads more like a textbook chapter on software specifications than an actionable skill that teaches Claude something new. The examples are placeholder-quality (generic auth system) and the entire document could be reduced to ~30 lines of actual novel guidance.
Suggestions
Reduce content to only what Claude doesn't already know—remove explanations of what specifications, use cases, and acceptance criteria are, and focus on project-specific conventions or non-obvious patterns.
Split the generic templates (SRS structure, API spec format, data model format) into separate reference files and keep SKILL.md as a concise overview with navigation links.
Add explicit validation checkpoints and feedback loops in the workflow, e.g., 'After gathering requirements, verify completeness by checking X before proceeding to constraint analysis.'
Replace the generic authentication example with guidance on how to adapt the specification process to arbitrary tasks, or remove examples entirely since Claude can generate specification templates on its own.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~200+ lines. Explains basic concepts Claude already knows (what a specification is, what requirements gathering means, what use cases are). The YAML/Gherkin examples are generic templates not specific to any real task. The entire 'Specification Deliverables' section is a generic SRS template that Claude can produce without instruction. The 'Best Practices' section states obvious advice like 'Be Specific' and 'Consider Edge Cases'. | 1 / 3 |
Actionability | Provides structured YAML templates and Gherkin examples that could serve as formats to follow, but they are generic placeholders (authentication system) rather than executable or directly usable guidance. The skill describes what a specification should contain rather than giving Claude concrete steps for how to analyze a real task and produce one. The validation checklist is somewhat actionable. | 2 / 3 |
Workflow Clarity | The numbered sections (1-4) provide a sequence for the specification process, and there's a validation checklist at the end. However, there are no explicit validation checkpoints between steps, no feedback loops for error recovery, and no clear decision points about when to proceed or iterate. The checklist is at the end rather than integrated into the workflow. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files. All content—templates, examples, deliverable formats, API specs, data models—is inlined in a single massive document. Much of this (API spec templates, data model templates, SRS structure) could be split into separate reference files with clear navigation from a concise overview. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- ruvnet/claude-flow
- Commit
322b2ae
- 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.