agent-specification

Agent skill for specification - invoke with $agent-specification

1.54x

Quality

13%

Does it follow best practices?

Impact

51%

1.54x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-specification/SKILL.md

Quality

Discovery

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 fails on all dimensions. It provides no concrete actions, no trigger terms, no 'when to use' guidance, and is so vague that it would be nearly impossible for Claude to correctly select this skill from a pool of available skills. It reads more like a label than a description.

Suggestions

Describe specific concrete actions the skill performs (e.g., 'Generates software requirement specifications, writes technical design documents, creates API specification files').

Add an explicit 'Use when...' clause with natural trigger terms (e.g., 'Use when the user asks to create, review, or edit specifications, requirements documents, or design docs').

Clarify the domain and type of specification to reduce conflict risk (e.g., software specs vs. hardware specs vs. API specs) and make the skill distinguishable from other document-related skills.

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, no description of capabilities, and no explicit trigger guidance.	1 / 3
Trigger Term Quality	The only potentially relevant keyword is 'specification', which is overly generic. There are no natural user-facing trigger terms. The invocation syntax '$agent-specification' is a command, not a natural language trigger.	1 / 3
Distinctiveness Conflict Risk	'Specification' is extremely broad and could overlap with any skill involving requirements, design docs, API specs, technical specs, etc. 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 an overly verbose, monolithic document that explains concepts Claude already understands (requirements gathering, acceptance criteria, use cases) using generic placeholder examples rather than providing targeted, actionable guidance. The templates are not executable and the content would benefit enormously from being split into separate reference files with a concise overview in the main skill. The validation checklist is a positive element but lacks integration into the workflow as explicit checkpoints.

Suggestions

Reduce the body to a concise overview (~30-50 lines) with the core specification workflow steps and checklist, moving the YAML templates, Gherkin examples, and API spec templates into separate referenced files (e.g., TEMPLATES.md, EXAMPLES.md).

Remove explanations of basic concepts Claude already knows (what specifications are, what users/roles/sessions mean, generic best practices like 'Be Specific').

Add explicit validation checkpoints between workflow steps (e.g., 'Verify all functional requirements have acceptance criteria before proceeding to constraint analysis').

Replace generic placeholder examples with guidance on how to adapt templates to the actual task context, or provide a concrete worked example showing the specification process applied to a real scenario.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~200+ lines. Explains basic concepts Claude already knows (what a specification is, what SPARC phases do, what users/roles/sessions are). The YAML/Gherkin examples are generic templates not specific to any real task. The 'Best Practices' section states obvious advice like 'Be Specific' and 'Consider Edge Cases.' The definitions section defining 'User' as 'Any person with system access' wastes tokens.	1 / 3
Actionability	Provides structured YAML templates and Gherkin examples that could serve as starting points, but everything is generic placeholder content (fictional auth system). There are no executable commands or real tool invocations—just template structures. The hook scripts reference undefined functions like 'memory_store' without explanation of what they do or how they work.	2 / 3
Workflow Clarity	The specification process is sequenced (Requirements Gathering → Constraint Analysis → Use Cases → Acceptance Criteria → Deliverables), 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 guidance on what to do if requirements are incomplete or contradictory.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content—requirements templates, data models, API specs, use cases, acceptance criteria—is inlined in a single massive document. Much of this (API spec templates, data model templates, Gherkin examples) should be in separate reference files with links from the main skill.	1 / 3
	Total	6 / 12 Passed

Validation

100%

Warnings & errors only

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: 0d9f9b1

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.