speckit-clarify

Detects specification ambiguities and integrates targeted clarification answers into spec files.

Updated Sep 9, 2026
One-click install
npx skills add https://github.com/MagnoAlves1993/handy --skill speckit-clarify-magnoalves1993
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: speckit-clarify
Source: https://github.com/MagnoAlves1993/handy/tree/main/.github/skills/speckit-clarify
Command: npx skills add https://github.com/MagnoAlves1993/handy --skill speckit-clarify-magnoalves1993

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Feature specifications often contain vague requirements, missing decisions, and ambiguous terms that cause rework during implementation. This Skill systematically scans a spec for underspecified areas and resolves them through focused questions before planning begins. ## Core Features & Use Cases - Structured Ambiguity Scan: Evaluates the spec across a taxonomy of categories including functional scope, data model, non-functional requirements, edge cases, and terminology, marking each as Clear, Partial, or Missing. - Interactive Clarification Loop: Asks up to 5 high-impact questions one at a time, each with a recommended multiple-choice option or suggested short answer, then writes accepted answers into a ## Clarifications section and updates the relevant spec sections. - Checklist Re-validation: Re-evaluates the spec quality checklist at checklists/requirements.md after updates, toggling only changed checkbox states and reporting pass counts. - Use Case: Before running /speckit-plan on a new feature spec, run this Skill to resolve open questions about security posture, data constraints, or acceptance criteria so the plan is built on unambiguous requirements. ## Quick Start Ask the assistant to run the speckit-clarify skill to review the current feature spec and resolve its ambiguities before planning.

Frequently Asked Questions about speckit-clarify

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clarify ambiguities in a feature specification?

Run the speckit-clarify skill after creating a spec with /speckit-specify. It scans the spec across categories like functional scope, data model, and edge cases, then asks up to 5 targeted questions and writes the answers directly into the spec file.

When should I run spec clarification in Spec Kit?

Run clarification after /speckit-specify and before /speckit-plan. Resolving ambiguities first reduces downstream rework risk, since the implementation plan and tasks are derived from the clarified requirements.

How many clarification questions does the skill ask?

It asks a maximum of 5 questions per session, presented one at a time. Each question is either multiple-choice with a recommended option or a short answer constrained to 5 words or fewer, prioritizing the highest-impact unresolved categories.

Does speckit-clarify work without a Spec Kit project structure?

No, it requires a Spec Kit project with a .specify directory and an existing feature spec. If the spec file is missing, it instructs you to run /speckit-specify first rather than creating a new spec.

What happens to the spec quality checklist after clarification?

If checklists/requirements.md exists in the feature directory, the skill re-evaluates each checkbox item against the updated spec. It toggles only markers whose pass/fail state changed and reports before and after pass counts in the completion report.