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

49%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/speckit-clarify/SKILL.md

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.

The content provides concrete, executable guidance and a well-sequenced workflow with validation checkpoints, but it is markedly verbose and inlines large reference-style material (the full ambiguity taxonomy and duplicated hook templates) rather than splitting it across bundle files. Progressive disclosure and token efficiency are the weakest aspects.

Suggestions

Move the full ambiguity taxonomy and the pre/post hook templates into separate reference files (e.g. references/taxonomy.md, references/hooks.md) and reference them one level deep from SKILL.md.

Trim restatements of concepts Claude already knows and collapse the duplicated pre/post extension-hook blocks into a single shared reference.

Tighten the integration and validation steps to a concise checklist; keep only the non-obvious rules inline.

Dimension	Reasoning	Score
Conciseness	The body is a ~230-line monolithic instruction set that re-states taxonomy and process Claude already knows (full ambiguity taxonomy, exhaustive integration sub-bullets, verbose hook templating duplicated pre/post) and could be cut substantially, making it noticeably verbose with several padded sections.	2 / 5
Actionability	Guidance is mostly executable: a concrete script invocation with exact flags ('check-prerequisites.ps1 -Json -PathsOnly'), precise JSON fields to parse, specific output formats, and explicit integration rules; only minor gaps keep it from copy-paste-perfect.	4 / 5
Workflow Clarity	An 8-step numbered sequence with clear validation (step 6 validation after each write, atomic save, exactly-one-bullet checks) and feedback handling; it slightly exceeds a single destructive write but has most checkpoints, with only minor validation gaps keeping it below 5.	4 / 5
Progressive Disclosure	There is section structure (User Input, Pre/Post-Execution Checks, Outline) but the entire workflow, taxonomy, and hook templates are inlined in SKILL.md with no bundle files present and no references split out, so content that should be separate stays inline and references are not signaled.	3 / 5
	Total	13 / 20 Passed

Description

42%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 clearly states what the skill does with several concrete actions, but it entirely lacks a 'Use when...' trigger clause and uses few natural user-facing trigger phrases, weakening both completeness and trigger-term quality. It is otherwise specific and reasonably distinct.

Suggestions

Add an explicit 'Use when...' trigger clause naming natural phrases a user would say, e.g. 'Use when the feature spec is vague, has gaps, or needs clarification before planning.'

Broaden trigger-term coverage to include synonyms users actually say: 'spec is unclear', 'what's missing from the spec', 'clarify requirements'.

Keep the concrete actions but ensure the description answers both 'what' and 'when' in a single sentence.

Dimension	Reasoning	Score
Specificity	Names the domain ('underspecified areas in the current feature spec') and several concrete actions ('asking up to 5 highly targeted clarification questions', 'encoding answers back into the spec'), with only minor coverage gaps relative to the full taxonomy of behavior in the body.	4 / 5
Completeness	The 'what' is present (identify underspecified areas, ask questions, encode answers) but there is no 'Use when...' or equivalent trigger clause, so the 'when' is entirely missing — the rubric caps such cases at 3 and the lack of any trigger guidance pulls it to 2.	2 / 5
Trigger Term Quality	It leans on the technical term 'feature spec' and 'clarification questions' but omits the natural phrasings a user would actually say ('the spec is vague', 'what's missing', 'clarify the requirements'); no synonyms or common variants are present.	2 / 5
Distinctiveness Conflict Risk	The niche is fairly distinct ('underspecified areas in the current feature spec', 'up to 5 targeted questions', 'encoding answers back into the spec') and unlikely to trigger for unrelated skills, with only minor overlap risk against generic spec/planning skills.	4 / 5
	Total	12 / 20 Passed

Validation

87%

Warnings & errors only

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

Criteria	Description	Result
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: unoplatform/uno
Path: .claude/skills/speckit-clarify/SKILL.md
Commit: eaa505e

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.