CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

56

Quality

64%

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

The canonical home for this skill is speckit-clarify in g14wx/staffSync

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.

An impressively rigorous, deterministic workflow with explicit sequencing, per-write validation, and feedback loops — the strongest part of the skill. Its weaknesses are the ~240-line monolithic body (including a near-verbatim duplicated hook procedure) and the absence of any reference files to split the taxonomy and hook mechanics into.

Suggestions

Deduplicate the Pre-/Post-Execution hook checks into a single shared procedure parameterized by the hooks key (before_clarify vs after_clarify), saving ~30 lines.

Move the full ambiguity taxonomy and hook output templates into references/ (e.g. references/taxonomy.md, references/hooks.md) and keep SKILL.md as a concise overview with clearly signaled one-level-deep links.

Trim over-specification (exact Markdown table layouts, the shell-quoting "I'm Groot" aside) and trust Claude's competence on formatting basics.

DimensionReasoningScore

Conciseness

The body is dense operational instruction rather than concept explanation, but at ~240 lines it could clearly be tightened: the extension-hook procedure is duplicated nearly verbatim in Pre- and Post-Execution Checks (~60 lines), quoting-escape advice for "I'm Groot" is oddly placed, and output formats are over-specified down to table layouts. It fits anchor 3 (mostly efficient but could be tightened) better than anchor 2, since nearly all prose is procedural rather than padding with things Claude already knows.

3 / 5

Actionability

Guidance is highly concrete and executable: the exact command ".specify/scripts/bash/check-prerequisites.sh --json --paths-only" with named JSON fields, exact output templates for hooks, exact bullet format "- Q: <question> → A: <final answer>", exact literal reply strings ("yes", "recommended", "suggested"), and exact failure handling. Not a 5 because there is no worked example of an actual question/table and a few details (e.g. the shell-escaping aside) are more confusing than actionable.

4 / 5

Workflow Clarity

Steps 1-8 are explicitly sequenced with a dedicated validation checklist after each write plus a final pass (step 6), error-recovery feedback loops (JSON parse failure aborts with recovery instructions; ambiguous answers trigger disambiguation without consuming the question quota), and early-termination rules. This matches the top anchor: clear sequence, explicit validation, feedback loops, and a checklist for a complex interactive process.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent), so everything — the ~60 lines of duplicated hook-checking procedure, the full 11-category taxonomy, and detailed formatting templates — is inlined in one 240-line SKILL.md. Section headers do provide internal structure, but content that clearly belongs in a one-level-deep reference file is inline, matching anchor 3 rather than 2 (structure exists) or 4 (nothing is split out).

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.

A solid, third-person description naming concrete actions, but it lacks any explicit "when to use" trigger clause and leans on one phrasing ("underspecified") rather than the natural vocabulary users would employ. Adding a Use-when clause with synonyms would lift completeness and trigger-term quality substantially.

Suggestions

Append an explicit trigger clause, e.g. "Use when the user mentions an unclear, vague, or incomplete feature spec, wants to resolve ambiguity/requirements gaps before planning, or says 'clarify the spec'."

Broaden trigger vocabulary with natural synonyms: "ambiguous/unclear requirements", "spec gaps", "missing decisions", not just "underspecified areas".

Optionally signal the spec-kit context ("in a spec-kit project") to sharpen distinctiveness from generic review/plan skills.

DimensionReasoningScore

Specificity

The description lists several concrete actions — "Identify underspecified areas", "asking up to 5 highly targeted clarification questions", "encoding answers back into the spec" — in third person. It is not a 5 because coverage is not comprehensive (the spec-update, taxonomy scan, and coverage-report behaviors are only implied by "encoding answers back"), and not a 3 because more than 1-2 distinct concrete actions are explicitly named.

4 / 5

Completeness

The "what" is clear (identify underspecified areas, ask up to 5 clarification questions, encode answers into the spec), but there is no "Use when..." clause or equivalent explicit trigger guidance — the "when" is only weakly implied by the spec context, which caps completeness at 3 per the judging guidelines.

3 / 5

Trigger Term Quality

Relevant keywords exist ("underspecified", "feature spec", "clarification questions") but common natural phrasings users would say — "ambiguous", "unclear requirements", "gaps in the spec", "spec review" — are missing, as are variations/synonyms. It sits above anchor 2 (which has only generic keywords) but below anchor 4 (good coverage with few missing terms).

3 / 5

Distinctiveness Conflict Risk

The feature-spec clarification framing is a distinct niche unlikely to fire for unrelated skills, but it does not mention the spec-kit context or distinguish itself from sibling skills in the same family (/speckit.specify, /speckit.plan), leaving minor overlap risk. Not a 5 because the trigger surface overlaps related spec-workflow skills; not a 3 because the action described is not something a sibling skill also claims to do.

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
mixpanel/mixpanel-headless
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.