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.
53
61%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/speckit-clarify/SKILL.mdQuality
Discovery
67%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 is strong in specificity and distinctiveness, clearly articulating a unique workflow of identifying spec gaps, asking clarification questions, and updating the spec. However, it lacks an explicit 'Use when...' clause and could benefit from more natural trigger terms that users would actually say when needing this skill.
Suggestions
Add a 'Use when...' clause such as 'Use when the user wants to review, refine, or flesh out a feature spec, or when requirements seem incomplete or ambiguous.'
Include additional natural trigger terms like 'spec review', 'requirements gaps', 'refine requirements', 'incomplete spec', or 'spec ambiguity' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'identify underspecified areas', 'asking up to 5 highly targeted clarification questions', and 'encoding answers back into the spec'. These are concrete, well-defined actions. | 3 / 3 |
Completeness | Clearly answers 'what does this do' (identify underspecified areas, ask clarification questions, encode answers into spec), but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'feature spec', 'clarification questions', and 'underspecified', but misses common user-facing variations like 'spec review', 'requirements', 'ambiguous', 'gaps in spec', or 'refine spec'. Users might not naturally use the phrase 'underspecified areas'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of feature spec refinement through targeted clarification questions and encoding answers back is a very specific niche. It's unlikely to conflict with general coding, documentation, or Q&A skills due to its narrow, well-defined scope. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable and has excellent workflow clarity with proper validation checkpoints and sequential questioning logic. However, it suffers significantly from verbosity—the hook-checking logic is duplicated, the taxonomy listing is exhaustive inline, and many instructions explain things Claude can infer. The monolithic structure with no progressive disclosure makes it a heavy context-window consumer that would benefit greatly from refactoring into a main overview with referenced supporting files.
Suggestions
Extract the duplicated pre/post hook-checking logic into a shared reference file (e.g., HOOKS.md) and reference it twice with a single line each, saving ~40 lines of duplication.
Move the ambiguity taxonomy (Functional Scope, Domain & Data Model, etc.) into a separate TAXONOMY.md file and reference it, reducing the main skill by ~30 lines.
Remove explanatory content Claude can infer, such as the single-quote escaping tip, the detailed explanation of how to parse JSON, and the narrative descriptions of each taxonomy category—replace with compact bullet lists.
Add a brief 'Quick Summary' section at the top (3-5 lines) that captures the core workflow before diving into detailed steps, improving scannability.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~200+ lines of detailed procedural instructions. Much of the content explains things Claude can infer (e.g., how to parse YAML, how to handle single quotes in shell args, detailed formatting instructions for markdown tables). The hook-checking logic is duplicated nearly verbatim for pre- and post-execution. The ambiguity taxonomy listing all categories with descriptions adds significant bulk that could be condensed into a compact checklist. | 1 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific shell commands (`check-prerequisites.sh --json --paths-only`), exact JSON fields to parse, precise formatting templates for questions and tables, explicit validation criteria, and detailed integration rules for where to place clarifications in the spec. The step-by-step process is fully specified with exact output formats. | 3 / 3 |
Workflow Clarity | The multi-step workflow is clearly sequenced (steps 1-8) with explicit validation checkpoints after each write (step 6), error recovery paths (disambiguation retries, early termination signals), and clear stop conditions (5-question limit, user signals). The incremental save-after-each-answer approach and final validation pass demonstrate strong feedback loops for this document manipulation task. | 3 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to supporting files, despite the complexity warranting separation. The hook-checking logic (duplicated for pre/post), the ambiguity taxonomy, and the question formatting rules could each be extracted into referenced files. No bundle files are provided to support this large body of content. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 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 | 9 / 11 Passed | |
- Repository
- mixpanel/mixpanel-headless
- Commit
3ce3191
- 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.