agent-specification

Agent skill for specification - invoke with $agent-specification

1.54x

Quality

—

Does it follow best practices?

Impact

51%

1.54x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

50%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a comprehensive specification template with concrete scaffolds and a closing validation checklist, but it is verbose, monolithic, and light on procedural guidance for how to actually run the specification process. It would benefit from trimming generic examples and moving detailed templates into reference files.

Suggestions

Trim the generic sample artifacts (full requirements doc, data model, OpenAPI spec) to minimal schema sketches and move the full exemplars into reference files under references/.

Reframe the 'Specification Process' as an explicit numbered procedure with validation checkpoints between phases rather than as labeled content sections.

Cut the 'Best Practices' section or compress it to a few non-obvious rules, since items like 'Be Specific' and 'Make it Testable' restate knowledge Claude already has.

Dimension	Reasoning	Score
Conciseness	The body is mostly structured templates rather than digressions, but it is padded with ~250 lines of generic boilerplate (full sample auth requirements doc, data model, OpenAPI spec) and best-practice platitudes Claude already knows, so it could be tightened considerably.	2 / 3
Actionability	It supplies concrete, copy-paste-ready scaffolds (YAML requirement/constraint/use-case schemas, Gherkin acceptance criteria, OpenAPI), but as an instruction-only skill it gives templates to fill rather than a concrete procedure for eliciting and validating the requirements themselves.	2 / 3
Workflow Clarity	A sequence is present (Specification Process steps 1-4 plus Deliverables) and a final Validation Checklist exists, but the steps read as content categories rather than a procedural workflow, with no inter-step checkpoints or fix-retry feedback loops.	2 / 3
Progressive Disclosure	The content is well-sectioned but monolithic: all ~250 lines sit inline in SKILL.md with no references to the (empty) references/scripts/assets bundles, so detailed templates that should be split out are not separated.	2 / 3
	Total	8 / 12 Passed

Description

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is a near-empty template line: it states the skill's name and how to invoke it but not what it concretely does or when to use it. It fails the 'what' and 'when' completeness test and offers no natural trigger terms.

Suggestions

Rewrite the description in third person listing concrete actions, e.g. 'Gathers requirements, analyzes constraints, and drafts acceptance criteria and use cases for the SPARC Specification phase.'

Add an explicit 'Use when...' clause with natural trigger terms such as 'requirements', 'specs', 'acceptance criteria', or 'SPARC specification phase'.

Remove the invocation jargon ('invoke with $agent-specification') from the description; invocation details belong elsewhere, not in the user-facing trigger text.

Dimension	Reasoning	Score
Specificity	The description only names a domain ('Agent skill for specification') and lists no concrete actions such as gathering requirements or drafting acceptance criteria, matching the vague/abstract anchor.	1 / 3
Completeness	It weakly gestures at 'what' (a specification skill) and has no 'Use when...' clause or equivalent trigger guidance, so both what and when are missing or very weak.	1 / 3
Trigger Term Quality	Beyond the bare word 'specification', the only trigger language is the invocation jargon 'invoke with $agent-specification', which a user would never naturally say when they need this skill.	1 / 3
Distinctiveness Conflict Risk	The named 'specification' domain gives it a partial niche, but the generic phrasing could still overlap with other requirements or analysis skills since no distinct triggers are stated.	2 / 3
	Total	5 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Commit: 8ae8752

Reviewed: 2 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.