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

46%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

38%Scale 1-5

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

This skill is essentially a large specification template inlined into a SKILL.md, explaining concepts and structures that Claude already understands well. While the template is reasonably well-organized and the quality checklist adds some value, the content is far too verbose for what it accomplishes—most of it restates standard software engineering practices. The skill would benefit greatly from being condensed to its unique value-add (the specific output format expectations and quality checklist) with detailed templates moved to bundle files.

Suggestions

Reduce the body to ~50-80 lines by removing explanations of concepts Claude already knows (service layer patterns, RBAC, circuit breakers, testing strategies) and focus only on the specific output structure expectations and quality checklist.

Move the detailed specification template (sections 1-8) into a separate TEMPLATE.md bundle file and reference it from SKILL.md, keeping only a brief summary of sections inline.

Add a concrete feedback loop to the workflow: after generating the spec, explicitly validate against the checklist, identify gaps, and iterate before presenting the final output.

Remove or drastically shorten the 'Best Practices' section—these are generic software engineering principles that Claude already follows and don't add novel instruction.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~250+ lines, mostly consisting of a generic specification template that Claude already knows how to produce. It explains concepts like service layer patterns, RBAC, circuit breakers, and testing strategies that Claude is deeply familiar with. The entire output format section is essentially a specification template that doesn't add novel knowledge.	2 / 5
Actionability	The skill provides a structured template with some concrete examples (API contract format, data model in Go, pseudocode for algorithms), but most guidance is at the level of 'include these sections' rather than executable steps. The examples are illustrative but not deeply actionable—they show format rather than providing copy-paste-ready tooling or commands.	3 / 5
Workflow Clarity	The task execution section at the end provides a rough sequence (read design → identify components → generate spec → review checklist), and the quality checklist serves as a validation step. However, there are no explicit feedback loops or error recovery steps—if the spec fails the checklist, there's no guidance on how to iterate. The workflow is implicit rather than explicitly sequenced with checkpoints.	3 / 5
Progressive Disclosure	The entire specification template, all examples, best practices, and the full output structure are inlined in a single monolithic file with no references to supporting files. The bulk of the content (the detailed template sections 1-8) would be better placed in a separate reference file, with SKILL.md serving as a concise overview. No bundle files exist to offload this content.	2 / 5
	Total	10 / 20 Passed

Description

53%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 establishes a clear purpose and includes an explicit 'Use when' clause, which is good. However, it lacks concrete actions (what specific artifacts or outputs does it produce?) and relies on somewhat abstract language. The trigger terms are adequate but miss many natural synonyms and variations users might employ.

Suggestions

Add specific concrete actions/outputs such as 'generates API contracts, defines data models, writes acceptance criteria, creates sequence diagrams, specifies error handling'.

Expand trigger terms to include natural synonyms like 'spec doc', 'technical design document', 'PRD', 'architecture spec', 'API specification', 'user stories'.

Improve distinctiveness by clarifying what differentiates this from general architecture or documentation skills, e.g., specifying the input-output transformation more precisely.

Dimension	Reasoning	Score
Specificity	Names the domain ('software specification') and a general action ('transforming high-level designs into detailed, implementable technical specifications'), but doesn't list concrete actions like 'generates API contracts', 'defines data models', 'writes acceptance criteria', etc. The description stays at a high level without enumerating specific deliverables or actions.	2 / 5
Completeness	Has both 'what' (transforming high-level designs into detailed technical specifications) and 'when' ('Use when converting requirements or designs into precise specs that developers can implement directly'). The 'when' clause is present but could be more specific with additional trigger scenarios.	4 / 5
Trigger Term Quality	Includes some relevant keywords like 'specification', 'requirements', 'designs', 'specs', and 'implement', but misses many natural terms users might say such as 'spec doc', 'technical design document', 'TDD', 'PRD', 'architecture', 'API spec', 'user stories', or 'acceptance criteria'.	3 / 5
Distinctiveness Conflict Risk	Could overlap with general software architecture skills, requirements gathering skills, or documentation skills. The term 'specification' helps narrow it somewhat, but 'requirements' and 'designs' are broad enough to conflict with related skills.	3 / 5
	Total	12 / 20 Passed

Validation

81%

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 — 9 / 11 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	9 / 11 Passed

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

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.