ask-questions-if-underspecified
Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.
62
47%
Does it follow best practices?
Impact
86%
1.56xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-mikeastock/skills/ask-questions-if-underspecified/SKILL.mdQuality
Discovery
17%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is too vague to be useful for skill selection. It fails to specify what kind of requirements are being clarified, what domain or technology is involved, or what concrete actions the skill performs. The only somewhat useful element is the explicit invocation constraint, but this does not compensate for the lack of specificity and trigger terms.
Suggestions
Specify the domain and concrete actions, e.g., 'Guides structured requirements gathering for software features by asking clarifying questions about scope, acceptance criteria, edge cases, and dependencies.'
Add natural trigger terms users would say, e.g., 'Use when explicitly asked to clarify requirements, gather specs, define acceptance criteria, or scope a feature before coding.'
Differentiate from other planning or analysis skills by naming the specific methodology or output format, e.g., 'Produces a structured requirements document with user stories and acceptance criteria.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language ('clarify requirements') without listing any concrete actions. It does not specify what kind of requirements, what domain, or what implementation means in this context. | 1 / 3 |
Completeness | It weakly addresses 'what' (clarify requirements before implementing) and has an explicit 'when' clause ('only when invoked explicitly'), but the 'when' is about invocation mode rather than describing the situations or user needs that should trigger this skill. The 'what' is too vague to be useful. | 2 / 3 |
Trigger Term Quality | The terms 'clarify requirements' and 'implementing' are generic and not natural keywords a user would say. There are no specific trigger terms that would help Claude match this skill to a user request. | 1 / 3 |
Distinctiveness Conflict Risk | The description is extremely generic — 'clarify requirements before implementing' could apply to virtually any development or planning skill. It provides no domain-specific or task-specific boundaries to distinguish it from other skills. | 1 / 3 |
Total | 5 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted behavioral skill with clear, sequenced workflow steps and highly actionable guidance including concrete question templates and reply formats. Its main weakness is minor verbosity—some content in the templates section overlaps with workflow guidance, and the underspecified criteria list could be more concise. Overall it's a strong skill that effectively teaches a specific interaction pattern.
Suggestions
Tighten the 'Decide whether the request is underspecified' checklist—Claude can infer several of these categories; focus on the non-obvious ones or collapse related items.
Consider consolidating the question templates section more tightly with the workflow step 2, as they partially overlap in guidance about formatting and defaults.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and avoids explaining concepts Claude already knows, but some sections could be tightened—e.g., the question templates section is somewhat repetitive with the workflow section, and the enumeration of what makes a request underspecified is slightly verbose given Claude's reasoning ability. | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: specific question templates with exact formatting, a code block showing the compact reply format, clear anti-patterns, and explicit behavioral rules (e.g., 'Do not run commands, edit files'). The guidance is copy-paste ready for interaction patterns. | 3 / 3 |
Workflow Clarity | The four-step workflow is clearly sequenced with explicit checkpoints: decide if underspecified → ask questions → pause before acting → confirm then proceed. The pause step serves as a validation checkpoint preventing premature action, and there's a clear feedback loop for when users want to proceed without answers (state assumptions → get confirmation). | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and logical sections, but it's all inline in a single file. The question templates and anti-patterns sections could potentially be separated for a cleaner overview, though for a skill of this size (~80 lines) it's borderline acceptable. The lack of any external references is fine given the scope, but the inline detail level is slightly heavy for a SKILL.md overview. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
47823e3
- 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.