CtrlK
BlogDocsLog inGet started
Tessl Logo

spec-driven-implementation

Drive a spec-first workflow for substantial features by writing PRODUCT.md before implementation, writing TECH.md when warranted, and keeping both specs updated as implementation evolves. Use when starting a significant feature, planning agent-driven implementation, or when the user wants product and tech specs checked into source control.

66

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/spec-driven-implementation/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

75%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.

A well-structured orchestrator skill: pragmatic decision criteria, concrete project-specific conventions and tool names, a clear six-step workflow with verification, and clean delegation to sibling skills. The main improvement opportunities are removing duplicated spec-currency guidance and making the verification step a closed feedback loop.

Suggestions

Consolidate the spec-update rules: section 5 and the Best Practices list repeat when to update PRODUCT.md vs TECH.md — state them once to save tokens.

Close the verification loop in step 6: add an explicit 'if verification fails, fix the code or update the spec, then re-verify' instruction so the workflow has a feedback cycle.

Annotate the Related Skills entries with one-line triggers (e.g., 'write-product-spec — when drafting PRODUCT.md') so navigation to each sibling skill is signaled.

DimensionReasoningScore

Conciseness

The body is lean, imperative, and teaches nothing Claude already knows — it spends its tokens on project-specific conventions (specs/ layout, Linear MCP tools) rather than general concepts. Minor repetition of spec-currency guidance across section 5 and Best Practices, plus a few bullets that could be merged, keep it at anchor 4 rather than 5.

4 / 5

Actionability

Concrete guidance throughout: exact paths ("specs/<linear-ticket-number>/PRODUCT.md"), named Linear MCP tools ("list_teams", "list_issue_labels", "save_issue"), "ask_user_question" for ambiguity, and explicit delegation to the write-product-spec / write-tech-spec / implement-specs skills. It is not anchor 5 because some steps (e.g., what to do when issue creation or verification fails) leave execution details to inference.

4 / 5

Workflow Clarity

Six clearly sequenced steps (decide → product spec → tech spec → implement → keep current → verify) with explicit decision criteria at step 1 and a verification checkpoint at step 6 that maps back to the specs. It stops short of anchor 5 because there is no explicit feedback loop for failed verification (no 'if verification fails, fix and re-verify' instruction), and anchor 3 would ignore that both decision and verification checkpoints are present.

4 / 5

Progressive Disclosure

The body is a well-sectioned overview with clear headers, no inlined bulk reference material, and a Related Skills section pointing to the three sibling skills it orchestrates. No bundle files exist, and none are needed for an orchestrator of this size. It is not anchor 5 because the related-skill pointers are bare names without signaling when to reach for each, a minor organization gap.

4 / 5

Total

16

/

20

Passed

Description

83%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.

A strong description: concrete third-person actions tied to named spec artifacts, an explicit 'Use when...' clause with multiple natural trigger phrases, and a clearly delineated spec-first niche. The only weaknesses are minor missing synonyms in trigger coverage and slight overlap with the sibling spec-writing skills it references.

DimensionReasoningScore

Specificity

"writing PRODUCT.md before implementation, writing TECH.md when warranted, and keeping both specs updated as implementation evolves" lists several concrete third-person actions tied to named artifacts. It falls short of anchor 5 because coverage of the workflow (verification, review) is only implied, and above anchor 3 because multiple specific actions are named rather than 1-2.

4 / 5

Completeness

The description explicitly answers what ("Drive a spec-first workflow for substantial features by writing PRODUCT.md before implementation...") and when ("Use when starting a significant feature, planning agent-driven implementation, or when the user wants product and tech specs checked into source control"), matching the anchor-5 exemplar structure with concrete trigger phrases. Neither the what nor the when is missing or vague, so 4 would undersell it.

5 / 5

Trigger Term Quality

Natural phrases like "starting a significant feature", "planning agent-driven implementation", and "product and tech specs checked into source control" are phrases a user would plausibly say. A few synonyms (e.g., "specification", "PRD") are missing, matching anchor 4's 'a few natural terms missing' rather than anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

Distinctive terms ("spec-first", "PRODUCT.md", "TECH.md", "spec-driven") carve a clear niche with minimal generic overlap. There is minor overlap risk with the closely related spec-writing skills it orchestrates (write-product-spec, write-tech-spec), which fits anchor 4 rather than anchor 5's 'minimal conflict risk'.

4 / 5

Total

17

/

20

Passed

Validation

100%

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
warpdotdev/common-skills
Reviewed

Table of Contents

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.