CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

speckit-specify

Create or update the feature specification from a natural language feature description.

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/speckit-specify/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

56%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 highly actionable, well-validated workflow for creating spec-kit feature specifications, with explicit feedback loops and checklists. Its main weaknesses are token waste from verbatim-duplicated hook rules and repeated clarification limits, a confusing nested step numbering, and a monolithic structure that inlines templates and hook logic that belong in reference files.

Suggestions

Extract the shared hook dispatch rules (extensions.yml parsing, enabled filtering, condition handling, dot-to-hyphen conversion) into a single shared section or a references/hooks.md file and reference it from both the pre- and post-execution sections, cutting ~40 duplicated lines.

Remove the 'CRITICAL - Table Formatting' guidance explaining pipe alignment and 3-dash separators — Claude already knows markdown table syntax — and drop one of the three restatements of the max-3 [NEEDS CLARIFICATION] limit.

Move the full checklist template and the question-format template into references/ files (e.g., references/checklist-template.md, references/question-format.md) so SKILL.md stays a concise overview, and flatten the doubled step numbering by merging the nested 'execution flow' sub-steps into the outer Outline steps.

DimensionReasoningScore

Conciseness

The hook dispatch rules (enabled-filtering, condition handling, dot-to-hyphen conversion) are repeated nearly verbatim in both the Pre-Execution Checks and Mandatory Post-Execution Hooks sections, the 'Maximum 3 [NEEDS CLARIFICATION]' rule is stated three times, the informed-guesses guidance is duplicated, and the 'CRITICAL - Table Formatting' block explains markdown table basics (pipe spacing, 3-dash separators) that Claude already knows. This matches 'noticeably verbose; several unnecessary explanations or padded sections' rather than the mostly-efficient anchor 3.

2 / 5

Actionability

Provides concrete executable guidance — '.specify/scripts/bash/resolve-template.sh spec-template --json', 'mkdir -p SPECIFY_FEATURE_DIRECTORY', exact file paths, the feature.json JSON format, and full markdown templates for the checklist and clarification questions. Minor gaps keep it below 5: hook invocation is described abstractly ('run it the same way you would run the command yourself') and several steps depend on unspecified TEMPLATE_CONTENT.

4 / 5

Workflow Clarity

The sequence (pre-hooks → spec creation → quality validation with a max-3-iteration fix/re-validate feedback loop → post-hooks → completion report → Done When checklist) is clear and well-checkpointed. It falls short of anchor 5 because the nested '6. Follow this execution flow' sub-steps 1-8 restate and interleave with the outer steps 1-8, creating a confusing doubled numbering.

4 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent) and all content is inlined in a single ~335-line file with reasonable section headers. Large self-contained blocks — the duplicated hook dispatch rules, the full checklist template, and the question format template — clearly belong in separate reference files, matching anchor 3 ('some structure... content that should be separate is inline').

3 / 5

Total

13

/

20

Passed

Description

50%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 states a clear, concrete capability in third person, but is a single bare sentence: it omits any 'when to use' trigger guidance, has thin keyword coverage, and nothing ties it to the spec-kit ecosystem to distinguish it from generic specification-writing skills. All dimensions land at the midpoint.

Suggestions

Add an explicit trigger clause, e.g., 'Use when the user describes a feature to specify, asks to create or update a spec, or mentions spec-kit/specify workflows.'

Broaden natural trigger terms to include synonyms users actually say: 'spec', 'write a spec', 'feature requirements', 'spec-kit', 'speckit'.

Anchor the description to the spec-kit context (e.g., 'within a spec-kit project') so it is distinguishable from generic requirements-drafting or planning skills.

DimensionReasoningScore

Specificity

'Create or update the feature specification from a natural language feature description' names the domain and one concrete action (creating/updating a spec from a description) but lists no further capabilities such as validation, checklists, or the clarification workflow — matching anchor 3, not anchor 4's 'several specific actions'.

3 / 5

Completeness

The 'what' is clear (create/update a feature specification from a natural language description), but there is no 'when' — no 'Use when...' clause or equivalent trigger guidance, which the rubric explicitly caps at 3. It is above anchor 2 because the 'what' is concrete, not vague.

3 / 5

Trigger Term Quality

The only natural keywords are 'feature specification' and 'feature description'; common phrasings users would actually say — 'spec', 'write a spec', 'requirements', 'spec-kit' — are missing, matching anchor 3 ('some relevant keywords but missing common variations or synonyms').

3 / 5

Distinctiveness Conflict Risk

'Feature specification' is somewhat specific, but the description never mentions spec-kit, speckit, or the .specify workflow, so it could overlap with generic spec-writing or requirements-drafting skills — anchor 3 ('somewhat specific but could still overlap'), below anchor 4's 'mostly distinct' since no distinctive triggers are named.

3 / 5

Total

12

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

RihardsJ/software-factory

Path

.claude/skills/speckit-specify/SKILL.md

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.