CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

speckit-specify

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

Quality

71%

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 ./tools/factory/.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 a highly actionable, well-sequenced orchestration procedure with explicit validation loops and copy-paste-ready commands, scripts, and templates. Its weaknesses are token efficiency (verbatim duplicated hook rules and triple-stated clarification limits) and the complete absence of progressive disclosure — a 335-line monolith with no external references.

Suggestions

Factor the hook dispatch rules (enabled/condition filtering, dot-to-hyphen conversion, output block formats) into a shared reference file and reference it from both the Pre-Execution and Post-Execution sections instead of duplicating ~40 lines verbatim.

Move the full Specification Quality Checklist template to references/checklist-template.md and keep only the file path and purpose inline.

State the [NEEDS CLARIFICATION] limit and priority order once (e.g., in the For AI Generation section) and cross-reference it from steps 6 and 8c.

DimensionReasoningScore

Conciseness

The body is dense with genuinely non-obvious operational detail, but it is noticeably padded: the hook dispatch rules are repeated verbatim in Pre-Execution Checks and Mandatory Post-Execution Hooks (~40 duplicated lines), the 3-marker clarification limit and priority ordering are stated three times (step 6, step 8c, and For AI Generation), and the full 35-line checklist template is inlined. This lands on anchor 3 (mostly efficient but could be tightened) rather than 2 because nothing explains concepts Claude already knows, and short of 4 because the duplication is substantial rather than minor.

3 / 5

Actionability

Guidance is fully executable: concrete commands ("resolve-template.sh spec-template --json", "mkdir -p"), an exact feature.json payload, a complete checklist file template, exact output block formats for hooks, a fully specified directory-name resolution order, and explicit error paths ("If it fails, stop and report the resolution error"). This matches anchor 5 — copy-paste ready instructions covering the common cases.

5 / 5

Workflow Clarity

The sequence is explicit (pre-hooks → numbered outline steps 1-8 → quality validation → post-hooks → completion report) with strong validation checkpoints: a spec quality checklist, a bounded re-validation loop (max 3 iterations), explicit failure handling, a user-response loop for clarifications, and a Done When checklist. This matches anchor 5 (clear sequence, explicit validation, feedback loops for error recovery).

5 / 5

Progressive Disclosure

There are no bundle files (references/, scripts/, assets/ all absent) and no references at all — everything lives in one ~335-line SKILL.md. Section headers keep it above anchor 2's minimal-structure profile, but content that clearly belongs in separate files is inlined (the checklist template, the duplicated hook dispatch rules), matching anchor 3 rather than 4 where content is actually split out.

3 / 5

Total

16

/

20

Passed

Description

53%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 a clear, third-person statement of what the skill does with a specific artifact and input, but it entirely lacks 'when to use' trigger guidance and natural trigger synonyms. It is serviceable but would misfire or fail to fire in ambiguous specification-writing contexts.

Suggestions

Add an explicit trigger clause, e.g., "Use when the user wants to turn a feature idea or product request into a structured spec, or asks to create/update a feature specification."

Include natural synonyms users would actually say — "spec", "write a spec", "feature spec", "product requirement" — to improve trigger-term coverage.

Mention the spec-kit context or the downstream commands (/speckit-clarify, /speckit-plan) to sharpen distinctiveness against sibling spec-editing skills.

DimensionReasoningScore

Specificity

"Create or update the feature specification" names a concrete artifact and 1-2 actions with a specific input ("natural language feature description"), matching the anchor for naming the domain with 1-2 concrete actions but not comprehensive coverage. It omits several capabilities the body actually performs (validation checklist, hook dispatch), so it falls short of anchor 4's several specific actions.

3 / 5

Completeness

The 'what' is clear (create/update a feature spec from a description) but there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. 'When' is at best weakly implied by "from a natural language feature description", so it does not reach anchor 4.

3 / 5

Trigger Term Quality

The only keywords are "feature specification" and "feature description" — relevant to the domain but missing natural variations users would say such as "spec", "write a spec", or "feature spec". This matches anchor 3 (some relevant keywords, missing common variations) rather than anchor 4's good keyword coverage.

3 / 5

Distinctiveness Conflict Risk

"The feature specification" names a distinct niche artifact with specific operations (create/update from a description), giving it a clear identity with only minor overlap risk against closely related sibling skills (e.g., /speckit-clarify also edits specs). It fits anchor 4 (mostly distinct, minor overlap) better than anchor 3's generic "works with document files" profile.

4 / 5

Total

13

/

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

tools/factory/.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.