agent-specification

Agent skill for specification - invoke with $agent-specification

1.54x

Quality

42%

Does it follow best practices?

Impact

51%

1.54x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-specification/SKILL.md

Quality

Content

56%Weight 40%Scale 1-5

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 thorough, well-templated specification guide with concrete, usable artifacts and a reasonable process sequence, but it is verbose and inlines large reference blocks that belong in separate files. It works as an inline reference more than a lean, navigable skill.

Suggestions

Move the bulky templates (requirements doc, data model, OpenAPI spec) into files under references/ and link to them from the body to reduce token load.

Trim generic boilerplate that Claude already knows (e.g. what functional vs non-functional requirements are) and keep only skill-specific guidance.

Add an explicit validate->fix->retry feedback loop so the specification checklist becomes an enforced checkpoint rather than a passive list.

Dimension	Reasoning	Score
Conciseness	The body inlines large generic specification templates (requirements/NFR YAML, a data model, an OpenAPI skeleton) that are padded boilerplate Claude largely already knows, fitting 'noticeably verbose; several unnecessary explanations or padded sections'.	2 / 5
Actionability	It provides concrete, copy-paste-ready YAML/Gherkin/OpenAPI templates and a validation checklist that are directly usable, with only minor gaps; it stops short of level 5 because guidance is mostly 'fill in this template' scaffolding rather than fully worked specific examples.	4 / 5
Workflow Clarity	There is a clear numbered Specification Process (1-4) plus Deliverables (1-3) and a 'Before completing' checklist that acts as a checkpoint, but no explicit validate->fix->retry feedback loop; this matches 'clear sequence with most checkpoints present'.	4 / 5
Progressive Disclosure	No bundle files exist and everything (templates, data model, API spec) is inlined in one monolithic file with section headers but no external references, fitting 'some structure but content that should be separate is inline'.	3 / 5
	Total	13 / 20 Passed

Description

28%Weight 40%Scale 1-5

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 minimal templated string that names only the domain and a bare invocation token, with no concrete actions, no natural trigger phrases, and no 'when to use' guidance. It would not help a user recognize when this skill is needed.

Suggestions

Replace the description with concrete actions in third person, e.g. 'Gathers requirements, analyzes constraints, and defines acceptance criteria for the SPARC specification phase'.

Add an explicit 'Use when...' clause with natural trigger phrases a user would say, such as 'requirements analysis', 'acceptance criteria', or 'defining scope'.

Remove the '$agent-specification' invocation token from the description; trigger guidance should describe scenarios, not how to call the skill.

Dimension	Reasoning	Score
Specificity	The description ('Agent skill for specification') names the domain but provides no concrete actions, matching the 'names the domain but actions are minimal or generic' anchor rather than the entirely-vague level 1 because a domain is at least identified.	2 / 5
Completeness	It gives a vague 'what' ('specification') and no 'when to use' guidance at all — only an invocation hint — so it fits the 'vague what and no when' anchor rather than level 3 which requires a clear 'what'.	2 / 5
Trigger Term Quality	The only trigger is the invocation token '$agent-specification', which is technical scaffolding rather than natural user language; it lacks phrases a user would actually say like 'requirements' or 'acceptance criteria'.	2 / 5
Distinctiveness Conflict Risk	'Specification' alone is broad and would overlap with other requirements/design skills, but the explicit '$agent-specification' token provides a distinct invocation hook, placing it at 'somewhat specific but could still overlap'.	3 / 5
	Total	9 / 20 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/ruflo
Path: .agents/skills/agent-specification/SKILL.md
Commit: fa13ee4

Reviewed: about 4 hours 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.