spec-driven-workflow

Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./engineering/skills/spec-driven-workflow/SKILL.md

Quality

Content

77%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 well-structured, highly actionable spec-first workflow with exemplary sequencing, validation checkpoints, and clean progressive disclosure into reference files. Its main weakness is rhetorical/motivational padding that inflates token cost without adding actionable value.

Suggestions

Trim the "Why Spec-First Matters" rationale and the dramatic "Iron Law" block to a single sentence each; Claude already understands the value of specification.

Fix script invocation paths to `python scripts/spec_validator.py ...` (and `scripts/spec_generator.py`, `scripts/test_extractor.py`) so commands run as-is from the skill root.

Compress the Anti-Patterns section from symptom/problem/rule prose into a compact table to cut tokens while preserving the rules.

Dimension	Reasoning	Score
Conciseness	The actionable core (spec format table, phases, commands, checklist) is efficient, but the "Why Spec-First Matters" rationale, the emphatic "Iron Law" block ("NO EXCEPTIONS. NO 'QUICK PROTOTYPES.'"), and the verbose symptom/problem/rule anti-pattern prose add unnecessary padding Claude could do without.	3 / 5
Actionability	Concrete copy-paste-ready commands (e.g. `python spec_validator.py --file spec.md --strict`), a tools table with example invocations, and an escalation template make it mostly executable, but scripts are invoked without their `scripts/` path prefix, so commands are not runnable as-is from the skill root.	4 / 5
Workflow Clarity	The 6-phase workflow gives each phase a goal, numbered steps, and explicit exit criteria, with a dedicated validation phase (`spec_validator.py --strict` plus a manual checklist), feedback loops ("If you discover a missing requirement, STOP and update the spec first"), and a self-review checklist.	5 / 5
Progressive Disclosure	SKILL.md is a well-organized overview that signals one-level-deep references to real files (spec_format_guide.md, acceptance_criteria_patterns.md, bounded_autonomy_rules.md) for the bulk detail, with templates and pattern libraries appropriately split out and easy navigation via the Cross-References section.	5 / 5
	Total	17 / 20 Passed

Description

66%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 gives strong, explicit, third-person trigger guidance with multiple concrete actions, but omits an explicit capability ("what") statement, leaving it in the mid-range on completeness. Distinctiveness and trigger quality are solid with only minor gaps.

Suggestions

Add an explicit 'what' clause, e.g. 'Guides a spec-first development workflow that produces requirements, acceptance criteria, and test stubs before implementation.' before the 'Use when' triggers.

Broaden trigger coverage with synonyms such as 'requirements', 'acceptance tests', and 'BDD/Given-When-Then' that users commonly say.

Tighten distinctiveness against TDD skills by framing test-generation as spec-derived rather than a standalone capability.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — "write specs before code", "define acceptance criteria", "plan features before implementation", "generate tests from specifications" — but they are process-level verbs with no concrete outputs, file types, or artifacts named, so it falls just short of comprehensive.	4 / 5
Completeness	The "when" is explicit and detailed (five distinct triggers under "Use when..."), but there is no standalone statement of what the skill does — the "what" is only implied by the trigger list, matching the clear-when/missing-what band rather than the both-present anchor.	3 / 5
Trigger Term Quality	Natural user-facing phrases like "write specs before code", "define acceptance criteria", and "generate tests from specifications" are present and clear, but common synonyms ("requirements", "acceptance tests", "BDD") are missing.	4 / 5
Distinctiveness Conflict Risk	The spec-first development niche is clearly framed and mostly distinct, though "generate tests from specifications" and "plan features before implementation" create minor overlap risk with TDD and general planning skills.	4 / 5
	Total	15 / 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: alirezarezvani/claude-skills
Path: engineering/skills/spec-driven-workflow/SKILL.md
Commit: 19392f7

Reviewed: ~5 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.