specify

Software specification expert for transforming high-level designs into detailed, implementable technical specifications. Use when converting requirements or designs into precise specs that developers can implement directly.

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/dev-skills/skills/specify/SKILL.md

Quality

Content

63%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 skill body is a thorough, well-structured spec-generation template with concrete examples and a clear workflow plus validation checklist. Its weaknesses are verbosity from redundant and generic sections, and a complete absence of progressive disclosure for a skill well over 50 lines.

Suggestions

Remove the duplicated workflow ('Task Execution' vs 'When given a design document') and trim the generic 'Best Practices' list to tighten conciseness.

Add an explicit review/fix feedback loop after the quality checklist (e.g., 'if a checklist item fails, revise the spec section and re-check before outputting').

Move the long example output and the detailed per-section templates into reference files (e.g., references/template.md, references/example-spec.md) and link to them one level deep to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The ~300-line body is mostly efficient as a template, but contains redundant sections ('Task Execution' duplicates the 'When given a design document' steps) and generic padding ('Best Practices' such as Be Precise/Be Complete, and security lists like RBAC/ABAC/JWT) that Claude already knows.	3 / 5
Actionability	Provides a concrete output template with real examples (a Go struct, an API contract block, pseudocode) and explicit argument-branching in 'Task Execution', so Claude knows exactly what to produce; minor gaps remain because examples are illustrative placeholders rather than copy-paste executable code.	4 / 5
Workflow Clarity	The process is sequenced (read → identify components → generate spec → review against the quality checklist → output) with the 'Specification Quality Checklist' serving as a validation checkpoint; it lacks an explicit fix-and-retry feedback loop and the duplicated task lists are a minor gap.	4 / 5
Progressive Disclosure	Section headers organize the content well, but at ~300 lines everything is inline with zero file references (no references/scripts/assets exist), and content that could be split out (the long example output, the detailed per-section templates) is monolithic.	3 / 5
	Total	14 / 20 Passed

Description

62%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 solid: third-person, explicit 'Use when' trigger, and a clear niche. It is held back by overlapping restated actions and limited trigger-term variety rather than a broad set of natural synonyms.

Suggestions

List several distinct concrete actions (e.g., 'draft functional/non-functional requirements, define API contracts, specify data models and migrations') instead of restating 'designs into specs' twice, to lift specificity.

Broaden trigger terms to natural phrasings users actually say, e.g., 'write a technical spec', 'turn this design doc into a spec', 'spec out this API or data model'.

Add concrete trigger contexts to the 'when' clause (e.g., 'when given a design doc, RFC, or requirements list to convert into an implementable spec').

Dimension	Reasoning	Score
Specificity	Names the domain and a concrete action ('transforming high-level designs into detailed, implementable technical specifications', 'converting requirements or designs into precise specs'), but these are essentially one action restated rather than several distinct actions, so it is not comprehensive.	3 / 5
Completeness	Explicitly answers both 'what' (transform designs into implementable specs) and 'when' ('Use when converting requirements or designs into precise specs'), though the 'when' could offer more varied concrete trigger phrases.	4 / 5
Trigger Term Quality	Includes relevant natural keywords ('specifications', 'specs', 'requirements', 'designs') but misses common variations users would say ('design doc', 'spec it out', 'RFC', 'write a spec').	3 / 5
Distinctiveness Conflict Risk	Specification-writing is a distinct niche with a clear trigger (specs from designs), with only minor overlap risk against general planning or design skills.	4 / 5
	Total	14 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: rikdc/ai-skills
Path: plugins/dev-skills/skills/specify/SKILL.md
Commit: cd15778

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.