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 provides virtually no useful information for skill selection. It fails on all dimensions — it doesn't describe what the skill does, when to use it, or include any natural trigger terms. It reads more like a label than a description.

Suggestions

Describe the concrete actions this skill performs (e.g., 'Generates software specification documents from requirements', 'Reviews and validates technical specifications').

Add an explicit 'Use when...' clause with natural trigger terms users would say (e.g., 'Use when the user asks to create, review, or edit a specification, requirements document, or technical design doc').

Clarify what type of specification this handles (software specs, API specs, product specs, etc.) to reduce conflict risk with other 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 the output is.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. There is no 'Use when...' clause and no description of capabilities.	1 / 3
Trigger Term Quality	The only keyword is 'specification', which is overly generic and not a natural trigger term users would use. The '$agent-specification' invocation syntax is not a natural language term a user would say.	1 / 3
Distinctiveness Conflict Risk	'Specification' is extremely broad and could overlap with any skill involving specs, requirements, documentation, design, or planning. There is nothing to distinguish this from other skills.	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 collection of generic specification templates that Claude already knows how to produce. It explains fundamental concepts (requirements gathering, use cases, acceptance criteria) at length without adding novel or project-specific guidance. The content would benefit enormously from being condensed to essential instructions with templates moved to referenced files.

Suggestions

Reduce content by 70%+ by removing generic templates and explanations of concepts Claude already knows (requirements gathering, use cases, Gherkin syntax, OpenAPI specs). Focus only on the specific workflow and decision criteria unique to this SPARC specification phase.

Move the YAML templates, Gherkin examples, SRS template, data model spec, and API spec into separate referenced files (e.g., TEMPLATES.md, EXAMPLES.md) and link to them from a concise overview.

Add explicit validation checkpoints between workflow steps, such as 'Verify all functional requirements have acceptance criteria before proceeding to constraint analysis' with concrete checks.

Replace generic authentication-system examples with guidance on how to adapt the specification process to the actual task at hand, including decision criteria for when to include/exclude certain specification elements.

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 SRS document template is boilerplate that Claude can generate on demand.	1 / 3
Actionability	Provides structured YAML templates and Gherkin examples that could serve as formats to follow, but everything is generic placeholder content (authentication system examples) rather than executable guidance. There are no actual commands to run or tools to invoke—it's a collection of templates rather than concrete instructions for performing specification work.	2 / 3
Workflow Clarity	The numbered sections (Requirements Gathering → Constraint Analysis → Use Case Definition → Acceptance Criteria) provide a sequence, 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 clear guidance on what to do if a step fails or stakeholders reject the specification.	2 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content—templates, examples, API specs, data models, checklists—is inlined in a single massive document. The deliverables section alone contains three large template blocks that should be separate reference files.	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/ruflo
Commit: 398f7c2

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.