ask-questions-if-underspecified

Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.

Quality

65%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/ask-questions-if-underspecified/SKILL.md

Quality

Content

88%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 tight, highly actionable instruction skill: a clear gated workflow, concrete templates, and explicit anti-patterns, with no padding. The only weaknesses are over-specified formatting micro-rules and a body slightly long for a skill that would otherwise score perfectly on structure.

Dimension	Reasoning	Score
Conciseness	The body is lean and operational — short bullets, concrete templates, no explanations of concepts Claude already knows. The default/recommended-choice formatting rules in step 2 ('bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block') are over-specified and could be trimmed, so it is not a 5.	4 / 5
Actionability	Fully concrete guidance for an instruction-only skill: exact question counts ('Ask 1-5 questions in the first pass'), copy-adaptable question templates, a complete reply-format example block, and an explicit fast-path ('Reply with: defaults (or 1a 2a)'). Nothing is left abstract; not lower because every section instructs rather than describes.	5 / 5
Workflow Clarity	A clearly sequenced 4-step workflow (decide underspecification → ask must-have questions → pause before acting → confirm interpretation then proceed) with explicit checkpoints: the pause gate ('Do not run commands, edit files...') and the confirmation step ('restate the requirements in 1-3 sentences... then start work'). Not a 4 because checkpoints are explicit, not implicit.	5 / 5
Progressive Disclosure	Well-organized single-file skill with clear sections (Goal, Workflow, Question templates, Anti-patterns) and no external references needed, so nothing is misplaced. It falls short of the automatic 5 for simple skills because the ~77-line body exceeds the under-50-line threshold and the workflow's step-2 detail could live in a short reference file; this matches the 'good structure; minor organization gaps' anchor.	4 / 5
	Total	18 / 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 communicates a clear core action but is thin: one concrete action, essentially one keyword phrase, and no positive trigger guidance. The explicit-invocation clause is a useful safeguard but does not substitute for natural 'Use when...' triggers.

Suggestions

Add a positive trigger clause, e.g., 'Use when a request is ambiguous, requirements are unclear, or multiple plausible interpretations exist' — this would lift both completeness and trigger_term_quality.

Include natural user phrasings/synonyms such as 'underspecified', 'ambiguous', 'unclear requirements', 'vague request' so the description matches what users actually say.

Enumerate the concrete behaviors (e.g., 'asks 1-5 prioritized clarifying questions, offers multiple-choice options with recommended defaults, pauses implementation until answered') to strengthen specificity.

Dimension	Reasoning	Score
Specificity	"Clarify requirements before implementing" names the domain and a single concrete action, matching the '1-2 concrete actions, but not comprehensive' anchor. It does not list several specific actions (4) nor reduce to a purely generic action (2).	3 / 5
Completeness	There is a clear 'what' (clarify requirements before implementing), but the only 'when' guidance is restrictive ("Do not use automatically, only when invoked explicitly") with no positive 'Use when...' triggers, so completeness is capped at 3 per the judging guidelines. Not a 4 because the 'when' does not tell a user (or Claude) which situations naturally call for the skill.	3 / 5
Trigger Term Quality	The only keyword phrase is "clarify requirements"; natural user phrasings like "requirements are unclear", "ambiguous", or "underspecified" (the latter only appears in the skill name) are missing. This fits the 'one or two generic keywords; missing the natural phrases users say' anchor.	2 / 5
Distinctiveness Conflict Risk	The phrasing is generic enough to overlap with planning, scoping, or requirements-gathering skills, though the "only when invoked explicitly" restriction meaningfully reduces accidental auto-trigger risk. Somewhat specific but overlapping — anchor 3.	3 / 5
	Total	11 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: MoizIbnYousaf/ai-agent-skills
Path: skills/ask-questions-if-underspecified/SKILL.md
Commit: 6d95c78

Reviewed: 6 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.