CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

speckit-specify

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

Quality

69%

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 ./apps/reference/.claude/skills/speckit-specify/SKILL.md

The canonical home for this skill is speckit-specify in RihardsJ/software-factory

SKILL.md
Quality
Evals
Security

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 an impressively rigorous command spec: exact commands, resolution orders, validation loops, and completion criteria make it highly actionable and workflow-clear. Its weaknesses are duplication (the hook protocol appears twice) and monolithic structure — a 330-line single file where a checklist template and hook protocol reference would reduce token cost and improve navigation.

Suggestions

Factor the shared extension-hook processing rules (extensions.yml parsing, enabled/condition handling, dot-to-hyphen command mapping) into a single referenced file or one shared section, and have both Pre- and Post-Execution sections reference it instead of duplicating ~25 lines each.

Move the full Specification Quality Checklist template to a referenced file (e.g., references/requirements-checklist.md) and keep only the validation procedure inline, cutting ~35 lines from the body.

Remove guidance that re-teaches known behavior, such as the 'CRITICAL - Table Formatting' spacing/preview rules and the 'For AI Generation' restatement of the clarification limits already specified in step 6.

DimensionReasoningScore

Conciseness

Mostly task-specific operational detail that earns its place, but the ~25-line extension-hook protocol is duplicated nearly verbatim in Pre-Execution Checks and Mandatory Post-Execution Hooks, the 'For AI Generation' section re-states the clarification limits from step 6, and table-formatting rules ('Each cell should have spaces around content', 'Test that the table renders correctly in markdown preview') explain what Claude already knows. Not 2 because the bulk is concrete instruction rather than concept padding.

3 / 5

Actionability

Fully executable guidance: exact commands ('.specify/scripts/bash/resolve-template.sh spec-template --json'), an explicit resolution order for SPECIFY_FEATURE_DIRECTORY, a literal JSON payload for .specify/feature.json, complete hook output templates, worked short-name examples, and good/bad success-criteria examples. Instruction-only skill whose guidance is copy-paste ready; matches anchor 5.

5 / 5

Workflow Clarity

Clear sequence (pre-hooks → 8-step outline → quality validation → post-hooks → completion report) with explicit validation steps, a feedback loop ('Re-run validation until all items pass (max 3 iterations)'), numbered clarification questions with a defined response format, and a 'Done When' checklist. Matches anchor 5: explicit validation, feedback loops, and checklists for a complex process. Not 4 — no checkpoints are missing.

5 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/ directories), so everything lives in a ~330-line SKILL.md. Section headers are clear, but content that clearly belongs in separate files — the 35-line checklist template and the duplicated hook protocol — is inlined, and there are no references at all. Fits anchor 3: some structure, but content that should be separate is inline. Not 4 because there is no reference navigation and the monolithic size impairs scanning.

3 / 5

Total

16

/

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 but stops at a single action and omits any usage trigger. All four dimensions land at the middle anchor for the same root cause: no "Use when..." clause and no synonym coverage. A modest rewrite adding trigger guidance and natural phrases would lift every dimension.

Suggestions

Add a 'Use when...' clause, e.g., 'Use when the user describes a feature to specify, asks to write or update a spec, or wants to turn a feature idea into a specification.'

Broaden trigger terms to natural synonyms users would say: 'spec', 'write a spec', 'spec out a feature', 'feature requirements', 'product spec'.

Mention one or two more concrete actions to raise specificity, e.g., '...validates it against a quality checklist and flags items needing clarification.'

DimensionReasoningScore

Specificity

Names 1-2 concrete actions ("Create or update the feature specification") and the input type ("from a natural language feature description"), but coverage is not comprehensive — no mention of validation, clarification, or checklist generation. Not 4 because only a single action pair is listed rather than several specific actions.

3 / 5

Completeness

Has a clear "what" (create/update the feature specification from a natural language description) but no "Use when..." clause or equivalent trigger guidance, which per the rubric caps completeness at 3. Not 4 because the "when" is entirely absent rather than merely implicit.

3 / 5

Trigger Term Quality

Contains relevant keywords ("feature specification", "feature description") but misses common natural variations users would say, such as "write a spec", "spec out a feature", or "requirements". Matches anchor 3: some relevant keywords, missing common synonyms.

3 / 5

Distinctiveness Conflict Risk

"Feature specification" is somewhat specific, but without any trigger context the description could overlap with related spec-workflow skills (e.g., clarify, plan, or generic spec-writing tasks). Fits anchor 3: somewhat specific but could still overlap with similar skills.

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

apps/reference/.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.