agent-specification
Agent skill for specification - invoke with $agent-specification
Install with Tessl CLI
npx tessl i github:ruvnet/claude-flow --skill agent-specification31
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 description is critically deficient across all dimensions. It provides no information about what the skill does, when to use it, or what domain it operates in. The only content is a vague label and an invocation command, which is insufficient for Claude to make informed skill selection decisions.
Suggestions
Add concrete actions describing what this skill does (e.g., 'Creates technical specifications', 'Generates API documentation', 'Writes requirements documents')
Include an explicit 'Use when...' clause with natural trigger terms users would say (e.g., 'Use when the user asks for specs, requirements, technical documentation, or system design')
Specify the domain or type of specifications this handles to distinguish it from other documentation or planning skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains no concrete actions whatsoever. 'Agent skill for specification' is completely abstract and does not describe what the skill actually does. | 1 / 3 |
Completeness | The description fails to answer both 'what does this do' and 'when should Claude use it'. There is no 'Use when...' clause and no explanation of capabilities. | 1 / 3 |
Trigger Term Quality | The only potential trigger term is '$agent-specification' which is technical jargon, not a natural keyword users would say. 'Specification' alone is too generic and vague. | 1 / 3 |
Distinctiveness Conflict Risk | 'Specification' is extremely generic and could conflict with many skills involving specs, requirements, documentation, or design. Nothing distinguishes this skill's niche. | 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 overly verbose, treating Claude like a junior analyst who needs to learn what requirements gathering is. The extensive template examples (YAML schemas, Gherkin scenarios, OpenAPI specs) are generic boilerplate that Claude already knows how to produce. The skill would be far more effective as a concise checklist of what to produce and quality criteria, with templates moved to separate reference files.
Suggestions
Reduce content by 75%+ by removing explanations of concepts Claude knows (use cases, acceptance criteria, Gherkin syntax) and keeping only project-specific guidance
Move template examples (YAML schemas, OpenAPI specs, data models) to separate reference files and link to them
Add explicit workflow with validation checkpoints: e.g., 'After gathering requirements, validate with user before proceeding to constraints'
Replace generic examples with guidance on how to extract requirements from the specific task context provided
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose with extensive YAML/code examples that explain basic concepts Claude already knows (requirements gathering, use cases, acceptance criteria). The 200+ lines could be condensed to ~50 lines of actionable guidance. | 1 / 3 |
Actionability | Provides concrete YAML/Gherkin examples and templates, but they're generic placeholders rather than executable guidance. The examples show format but don't instruct Claude on how to actually gather requirements or analyze a specific task. | 2 / 3 |
Workflow Clarity | Lists a 4-step specification process and includes a validation checklist, but lacks explicit checkpoints or feedback loops. The checklist at the end is good but disconnected from the workflow steps. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files. All content is inline including lengthy API specs, data models, and requirements documents that should be separate reference materials. | 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.
- 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.