Clarify a proposed task, plan, or design update by interrogating the highest-value unresolved decisions until the inputs are ready for task creation, task planning, or task/design updates. Use this as the default clarification path for Spec Loop task creation, task updates, and any planning, approval, or implementation step that encounters material unresolved questions that are user-preference-sensitive or could materially change scope, constraints, design, or test specification. When clarification ends, resume the invoking workflow. It may also be used for general grilling when explicitly selected or when no other default grilling skill is available.
62
72%
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 ./skills/spec-loop-clarify-task/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 reasonably complete, clearly stating both what the skill does and when to use it, with explicit trigger conditions tied to a specific workflow (Spec Loop). However, it relies heavily on internal jargon and abstract concepts rather than concrete actions or natural user language, which weakens specificity and trigger term quality. The broad fallback clause ('general grilling') slightly undermines distinctiveness.
Suggestions
Add more natural trigger terms users might actually say, such as 'unclear requirements', 'need more details', 'ambiguous spec', or 'missing information' to improve discoverability.
List more concrete actions the skill performs (e.g., 'asks targeted questions about scope, constraints, acceptance criteria, and design trade-offs') rather than abstract descriptions like 'interrogating the highest-value unresolved decisions'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain (clarification/interrogation of decisions) and some actions ('interrogating the highest-value unresolved decisions'), but the actions are somewhat abstract rather than listing multiple concrete, discrete operations. Terms like 'material unresolved questions' and 'user-preference-sensitive' are conceptual rather than concrete. | 2 / 3 |
Completeness | The description clearly answers both 'what' (interrogate highest-value unresolved decisions until inputs are ready) and 'when' (default clarification path for Spec Loop task creation, task updates, planning/approval/implementation steps with material unresolved questions, and general grilling when explicitly selected). The 'Use this as the default clarification path...' clause serves as an explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'clarification', 'task creation', 'task planning', 'task updates', 'design updates', 'grilling', and 'Spec Loop', but these are fairly domain-specific jargon. Missing more natural user-facing terms a person might say like 'ask questions', 'need more info', 'unclear requirements', or 'ambiguous'. | 2 / 3 |
Distinctiveness Conflict Risk | The description carves out a niche around clarification and grilling within a Spec Loop workflow, which is fairly specific. However, the mention of 'general grilling when explicitly selected or when no other default grilling skill is available' broadens scope and could overlap with other questioning/clarification skills. The phrase 'any planning, approval, or implementation step' is also quite broad. | 2 / 3 |
Total | 9 / 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 procedural skill that provides highly specific, actionable guidance for a clarification workflow. Its strengths are the precise decision-making protocol with concrete thresholds, formats, and exit criteria. Its main weaknesses are moderate verbosity (particularly around batch presentation rules which are restated with variations) and a monolithic structure that could benefit from clearer section headers to aid navigation.
Suggestions
Add section headers (e.g., ## Branch Selection, ## Confidence-Based Resolution, ## Decision Batch Presentation, ## Question Format) to break up the monolithic content and improve scannability.
Consolidate the batch presentation rules into a single, tighter block—currently the rules about presenting batches, not silently applying decisions, and timing of presentation are spread across multiple paragraphs with overlapping content.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly long and contains some repetitive phrasing (e.g., the batch presentation rules are restated multiple times with slight variations). However, most content is genuinely instructional and not explaining concepts Claude already knows—it's defining a specific protocol. Some tightening is possible, particularly around the decision batch presentation rules. | 2 / 3 |
Actionability | The skill provides highly specific, concrete guidance: exact formats for Decision and Recommendation lines, precise confidence thresholds (80%, 90%, 100%), explicit batch size limits, clear sequencing rules, and an exit checklist. While there's no executable code, this is an instruction-only skill where the guidance is fully actionable and unambiguous. | 3 / 3 |
Workflow Clarity | The multi-step clarification process is clearly sequenced: select branch by importance/uncertainty, traverse depth-first, resolve or ask based on confidence thresholds, present decisions in batches, wait for confirmation, and exit only after the explicit exit checklist passes. Validation checkpoints are explicit (exit check, confirmation before proceeding, contradiction surfacing). The feedback loop of resolve → present → confirm/disagree → continue is well-defined. | 3 / 3 |
Progressive Disclosure | The skill references external workflow files (spec-loop-plan-task, spec-loop-prepare-implementation-approval, spec-loop-implementation-flow) which is good navigation. However, the content itself is monolithic—all rules are inline in a single file with no section headers beyond the exit check. The dense protocol rules could benefit from clearer structural organization (e.g., separate sections for branch selection, confidence-based resolution, batch presentation, question format). | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
90f996e
Table of Contents
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.