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 description is critically deficient across all dimensions. It provides no concrete actions, no trigger terms, no 'when to use' guidance, and no distinguishing characteristics. It is essentially a label with an invocation command rather than a functional description that would allow Claude to select this skill appropriately.

Suggestions

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

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 technical design docs').

Clarify the domain of 'specification' to reduce conflict risk — is this software specs, product specs, hardware specs? Be explicit about the niche.

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Agent skill for specification' is extremely vague — it doesn't explain 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 terms a user would say, and '$agent-specification' is an invocation command, not a trigger term.	1 / 3
Distinctiveness Conflict Risk	'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 a verbose, textbook-style document that explains specification concepts Claude already understands, using generic authentication examples as templates. It lacks token efficiency, stuffing ~200 lines of templates and obvious advice into a single file with no progressive disclosure. While the YAML/Gherkin templates provide some structural guidance, the skill would benefit enormously from being condensed to essential instructions and splitting reference templates into separate files.

Suggestions

Reduce content by 60-70%: Remove explanations of what specifications are, what requirements gathering means, and obvious best practices. Focus only on the specific output format and process Claude should follow.

Split template examples (YAML requirement format, Gherkin templates, API spec templates, data model templates) into separate reference files and link to them from a concise overview.

Add explicit validation checkpoints between workflow steps, e.g., 'After gathering requirements, verify each has measurable acceptance criteria before proceeding to constraint analysis.'

Replace the generic authentication example with a brief, parameterized template showing how to adapt the format to any domain, rather than a full worked example.

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 'Best Practices' section contains obvious advice like 'Be Specific' and 'Consider Edge Cases.' The entire document reads like a textbook chapter rather than actionable skill instructions.	1 / 3
Actionability	Provides structured YAML templates and Gherkin examples that could serve as formats to follow, but they are generic examples (user authentication) rather than executable guidance. Claude doesn't know what specific task to apply these to or how to adapt them. The templates give some concrete structure but are essentially pseudocode/placeholder content rather than copy-paste ready instructions.	2 / 3
Workflow Clarity	The specification process is listed as numbered steps (Requirements Gathering, Constraint Analysis, Use Case Definition, Acceptance Criteria) and there's a validation checklist at the end. However, the steps lack explicit sequencing logic, validation checkpoints between steps, or feedback loops for when specifications fail review. The checklist is present but disconnected from the workflow.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content—templates, examples, deliverables, API specs, data models—is inlined in a single massive document. Much of this content (API spec templates, data model templates, full requirements document templates) should be in separate reference files. No bundle files exist to support this either.	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: ca77f83

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.