CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

speckit-clarify

Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.

Quality

70%

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 ./tools/factory/.claude/skills/speckit-clarify/SKILL.md

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

SKILL.md
Quality
Evals
Security

Quality

Content

70%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 exceptionally precise, executable procedure with strong validation checkpoints and feedback loops, but it is over-long for a single file: the hook protocol is stated twice verbatim and the taxonomy would live better in a reference file. Adding one worked example and deduplicating the hook rules would raise both actionability and conciseness.

Suggestions

Factor the duplicated extension-hook protocol into a single shared section or reference file (e.g., references/hooks.md) and reference it from both the pre- and post-execution phases with only the hooks key differing.

Move the ~50-line ambiguity taxonomy to references/ambiguity-taxonomy.md, keeping a one-line-per-category summary in the body.

Add one worked example showing a filled-in multiple-choice question, a user reply, and the resulting spec edit so the format templates have a concrete common-case demonstration.

DimensionReasoningScore

Conciseness

Most content is operationally necessary, but the ~40-line extension-hook protocol is duplicated nearly verbatim between Pre-Execution Checks and Mandatory Post-Execution Hooks, and asides like the shell-quoting example ('I'm Groot') and repeated self-check rules could be trimmed. This is more than minor over-explanation, so it sits below the 'efficient' anchor.

3 / 5

Actionability

Guidance is highly concrete — exact script invocation ('check-prerequisites.sh --json --paths-only'), exact output block templates, exact option-table formats, and exact reply-handling rules ('yes', 'recommended', 'suggested'). The minor gap is that templates are placeholders with no worked end-to-end example of a question, answer, and resulting spec edit.

4 / 5

Workflow Clarity

The 9 numbered execution steps are clearly sequenced with explicit validation after each spec write plus a final pass, checklist re-validation with before/after snapshots, a disambiguation feedback loop for ambiguous answers, error-recovery paths (abort on JSON parse failure), and a 'Done When' checklist — matching the top anchor.

5 / 5

Progressive Disclosure

Section headers are clear and logically ordered, but the ~50-line ambiguity taxonomy and the duplicated hook protocol are inlined in a ~280-line single file with no external references, where anchor 3 ('content that should be separate is inline') fits better than anchor 4.

3 / 5

Total

15

/

20

Passed

Description

58%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 purpose with specific actions and a bounded question quota, but it omits any 'when to use' trigger guidance and lacks natural synonym terms like 'ambiguous' or 'unclear requirements'. Adding an explicit use-when clause and common trigger phrases would lift it from adequate to strong.

Suggestions

Append an explicit trigger clause, e.g., 'Use when a feature spec contains ambiguities, unresolved decisions, or vague requirements before running /speckit-plan.'

Include natural synonym phrases users would actually say — 'ambiguous spec', 'unclear requirements', 'spec clarification' — alongside 'underspecified areas'.

Briefly mention the downstream integration outcome (updated spec with a Clarifications section) to sharpen the 'what' against sibling spec-kit commands.

DimensionReasoningScore

Specificity

Names the domain (feature spec clarification) and three concrete actions — 'Identify underspecified areas', 'asking up to 5 highly targeted clarification questions', 'encoding answers back into the spec'. Minor gaps remain (checklist re-validation and coverage reporting are unstated), so it does not reach comprehensive coverage.

4 / 5

Completeness

The 'what' is clear (identify ambiguity, ask up to 5 targeted questions, encode answers into the spec), but there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines.

3 / 5

Trigger Term Quality

Relevant keywords like 'underspecified areas', 'clarification questions', and 'feature spec' are present, but common variations users would naturally say — 'ambiguous', 'unclear requirements', 'spec-kit' — are missing, matching the 'missing common variations or synonyms' anchor.

3 / 5

Distinctiveness Conflict Risk

The feature-spec clarification niche is mostly distinct with concrete trigger concepts ('underspecified areas', 'clarification questions'), with only minor overlap risk against closely related spec-kit skills such as plan or review workflows.

4 / 5

Total

14

/

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-clarify/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.