create-spec skill
Creates comprehensive product or feature specification documents through an adaptive, multi-round interview process.
- GitHub stars
- 45
- Files
- 6
- Last commit
- May 31, 2026
- License
- MIT
- Allowed tools
- 10
What does the create-spec skill do?
create-spec creates comprehensive product or feature specification documents through an adaptive, multi-round interview process.
Summary generated from the skill's SKILL.md.
About the create-spec skill
Product managers and engineers can use this skill to generate detailed product or feature specification documents through a structured, multi-round interview process. Instead of simply writing a document based on a brief prompt, the agent conducts an adaptive conversation to uncover requirements, technical constraints, and success metrics. It is designed to be used when a user wants to start a new specification, and it can ingest existing context from markdown or text files to make the interview more targeted.
The workflow adapts its depth based on whether the user needs a high-level overview, detailed specifications, or full technical documentation. It uses the AskUserQuestion tool for all user interactions to ensure structured input and can even trigger codebase exploration for new features using team-based patterns. The process concludes by presenting a summary for confirmation before compiling the final specification into a file, ensuring the output is a complete planning artifact rather than just an implementation plan.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the create-spec skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the create-spec skill in Plugin
/plugin marketplace add sequenzia/agent-alchemy /plugin install agent-alchemy-sdd-tools@agent-alchemy
Install the create-spec skill in Claude Code
~/.claude/skills/create-spec/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec ~/.claude/skills/create-specInstall the create-spec skill in Claude Code (project)
.claude/skills/create-spec/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec .claude/skills/create-specInstall the create-spec skill in Codex
~/.agents/skills/create-spec/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec ~/.agents/skills/create-specInstall the create-spec skill in Gemini CLI
~/.gemini/skills/create-spec/SKILL.md
$ npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec ~/.gemini/skills/create-specInstall the create-spec skill in Claude.ai
npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec create-spec && zip -r create-spec.zip create-spec # claude.ai → Customize → Skills → + → Create skill → Upload a skill → create-spec.zip
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec is public and reachablegithub.com/sequenzia/agent-alchemy/tree/HEAD/claude/sdd-tool ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-05-31github.com/sequenzia/agent-alchemy/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/sequenzia/agent-alchemy/blob/HEAD/claude/sdd-tool ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/sequenzia/agent-alchemy/blob/HEAD/claude/sdd-tool ↗Finding
- SKILL.md follows the Agent Skills formatSKILL.md is 743 lines; the spec suggests under 500github.com/sequenzia/agent-alchemy/blob/HEAD/claude/sdd-tool ↗Finding
SKILL.md
View on GitHubCreate Spec Skill
You are initiating the spec creation workflow. This process gathers requirements through an adaptive, multi-round interview and generates a comprehensive specification document.
Critical Rules
AskUserQuestion is MANDATORY
IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.
- Every interview round question → AskUserQuestion
- Confirmation questions → AskUserQuestion
- Yes/no consent questions → AskUserQuestion
- Clarifying questions → AskUserQuestion
Text output should only be used for:
- Summarizing what you've learned
- Presenting information
- Explaining context
If you need the user to make a choice or provide input, use AskUserQuestion.
NEVER do this (asking via text output):
What features are most important to you?
1. Performance
2. Usability
3. Security
ALWAYS do this (using AskUserQuestion tool):
AskUserQuestion:
questions:
- header: "Priority"
question: "What features are most important to you?"
options:
- label: "Performance"
description: "Speed and responsiveness"
- label: "Usability"
description: "Ease of use"
- label: "Security"
description: "Data protection"
multiSelect: true
Plan Mode Behavior
CRITICAL: This skill generates a spec document, NOT an implementation plan. When invoked during Claude Code's plan mode:
- DO NOT create an implementation plan for how to build the spec's described features
- DO NOT defer spec generation to an "execution phase"
- DO proceed with the full interview and spec generation workflow immediately
- DO write the spec file to the output path as normal
The spec is a planning artifact itself — generating it IS the planning activity.
Load Reference Skills
When codebase exploration is triggered (Phase 2, "new feature" type), load the teams reference for the Parallel Specialists exploration pattern:
Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/SKILL.md
This provides TeamCreate, SendMessage, and team lifecycle conventions used in the codebase exploration procedure.
Workflow Overview
This workflow has six phases:
- Settings Check — Load user configuration
- Initial Inputs — Gather spec name, type, depth, and description (includes team-based codebase exploration for "new feature" type)
- Adaptive Interview — Multi-round depth-aware interview with recommendations and optional research
- Recommendations Round — Dedicated round for accumulated best-practice suggestions (if applicable)
- Pre-Compilation Summary — Present gathered requirements for user confirmation
- Spec Compilation — Generate spec from template and write to file
Phase 1: Settings Check
Check if there is a settings file at .claude/agent-alchemy.local.md to get any custom configuration like output path or author name.
Phase 2: Initial Inputs & Context
Context Loading
If $ARGUMENTS is provided, load user-supplied context before gathering initial inputs:
-
Determine input type:
- If the argument looks like a file path (ends in
.md,.txt, or.markdown; or starts with/,./,../, or~; or contains path separators and the file exists) → read the file using theReadtool - Otherwise → treat the entire argument string as inline context text
- If the argument looks like a file path (ends in
-
Store internally as "User-Supplied Context" for use throughout the interview
-
CRITICAL: User-supplied context makes the interview smarter, not shorter. Do NOT pre-fill answers or skip questions based on context. Instead:
- Ask more targeted, specific questions informed by the context
- Probe areas the context doesn't cover
- Confirm implicit assumptions the context makes
- Reference specific details from the context when asking questions
If $ARGUMENTS is empty, skip this subsection entirely — the skill behaves exactly as before.
Complexity Assessment
If user-supplied context was loaded, assess its complexity:
- Read
references/complexity-signals.mdfor signal definitions and thresholds - Scan the user-supplied context for complexity signals
- If threshold is met (3+ high-weight signals OR 5+ any-weight signals), present a brief notice via
AskUserQuestion:questions: - header: "Complexity" question: "This appears to involve significant complexity (e.g., {top 2-3 complexity areas}). The interview will be more thorough to ensure complete coverage. Ready to proceed?" options: - label: "Yes, let's be thorough" description: "Use expanded interview budgets for deeper coverage" - label: "Keep it brief" description: "Use standard interview budgets" multiSelect: false - If user selects "Yes, let's be thorough" → set internal
complexity_detectedflag for expanded budgets - If user selects "Keep it brief" → proceed with standard budgets
- If no context was loaded or threshold was not met → proceed with standard budgets (no alert shown)
Gather Initial Inputs
Use AskUserQuestion to gather the essential starting information with these four questions:
Question 1 - Spec Name:
- Header: "Spec Name"
- Question: "What would you like to name this spec?"
- Options: Allow text input for a descriptive name
Question 2 - Type:
- Header: "Type"
- Question: "What type of product/feature is this?"
- Options:
- "New product" - A completely new product being built from scratch
- "New feature" - A new feature for an existing product
Question 3 - Depth:
- Header: "Depth"
- Question: "How detailed should the spec be?"
- Options:
- "High-level overview (Recommended)" - Executive summary with key features and goals
- "Detailed specifications" - Standard spec with acceptance criteria and phases
- "Full technical documentation" - Comprehensive specs with API definitions and data models
Question 4 - Description:
- Header: "Description"
- If context was loaded: "I've loaded the context you provided. Is there anything it doesn't cover, or would you like to highlight specific priorities?"
- If no context: "Briefly describe the product/feature and its key requirements"
- Options: Allow text input describing the problem, main features, and constraints
Phase 3: Adaptive Interview
Prepare for Interview
Before starting Round 1, read these reference files to load the full question bank and trigger patterns:
references/interview-questions.md— Question bank organized by category and depth levelreferences/recommendation-triggers.md— Trigger patterns for proactive recommendations across all domains
Use these as your primary source for questions and trigger detection throughout the interview.
Interview Strategy
Depth-Aware Questioning
Adapt your interview depth based on the requested level:
High-level overview (2-3 rounds):
- Focus on problem, goals, key features, and success metrics
- Skip deep technical details
- Ask broader, strategic questions
- Total of 6-10 questions across all rounds
Detailed specifications (3-4 rounds):
- Balanced coverage of all categories
- Include acceptance criteria for features
- Cover technical constraints without deep architecture
- Total of 12-18 questions across all rounds
Full technical documentation (4-5 rounds):
- Deep probing on all areas
- Request specific API endpoints, data models
- Detailed performance and security requirements
- Total of 18-25 questions across all rounds
Question Categories
Cover all four categories, but adjust depth based on level:
- Problem & Goals: Problem statement, success metrics, user personas, business value
- Functional Requirements: Features, user stories, acceptance criteria, workflows
- Technical Specs: Architecture, tech stack, data models, APIs, constraints
- Implementation: Phases, dependencies, risks, out of scope items
Expanded Budgets
When complexity_detected is set (user opted in after complexity assessment), use expanded budgets from references/interview-questions.md (section "Expanded Budgets (Complexity Detected)") instead of the standard budgets above. Soft ceiling of ~8 rounds / ~35 questions applies.
Adaptive Behavior
- Build on previous answers: Reference what the user already told you
- Skip irrelevant questions: If user says "no preference" on tech stack, skip detailed tech questions
- Probe deeper on important areas: If user indicates something is critical, ask follow-up questions
- Explore codebase when helpful: For "new feature" type, offer to explore relevant code (with user approval)
- If something is unclear, ask for clarification rather than assuming
Context-Informed Questioning
When user-supplied context was loaded in Phase 2, apply these strategies throughout the interview:
- Reference specifics from context when asking questions — e.g., "Your context mentions a notification service — what events should trigger notifications?"
- Identify gaps in context and probe those first — areas the context doesn't address are the highest-value questions
- Confirm assumptions the context implies but doesn't state — e.g., "The context describes multiple services. Should these be independently deployable microservices?"
- Skip surface-level questions and go deeper — don't ask "what are you building?" when the context already describes it; instead ask about edge cases, constraints, and trade-offs
- Cross-reference with complexity signals — ensure areas that drove the complexity assessment get thorough coverage in the interview
Round Structure
Each round MUST:
- Summarize what you've learned so far (briefly) — use text output
- Ask 3-5 focused questions using
AskUserQuestion— REQUIRED, never use text for questions - Use a mix of multiple choice (for structured data) and open text (for details)
- Detect triggers: Note any recommendation triggers in user responses
- Offer inline insights (optional): If triggers detected, offer 1-2 brief recommendations
- Acknowledge responses before moving to next round
Question Guidelines:
- Keep questions clear and specific
- Provide helpful options for multiple choice where appropriate
- Use "Other" option for flexibility
- Group related questions together
- Don't overwhelm — max 4 questions per AskUserQuestion call
Example Question Patterns:
For structured choices:
header: "Priority"
question: "What priority is this feature?"
options:
- label: "P0 - Critical"
description: "Must have for initial release"
- label: "P1 - High"
description: "Important but can follow fast"
- label: "P2 - Medium"
description: "Nice to have"
For open-ended input:
header: "Problem"
question: "What specific problem are you trying to solve?"
options:
- label: "Efficiency"
description: "Users spend too much time on manual tasks"
- label: "Quality"
description: "Current solution produces errors or poor results"
- label: "Access"
description: "Users can't do something they need to do"
Proactive Recommendations
Throughout the interview, watch for patterns in user responses that indicate opportunities for best-practice recommendations. When detected, offer relevant suggestions based on industry standards.
Trigger Detection: After receiving user responses each round, scan for trigger keywords from the loaded references/recommendation-triggers.md. The file covers domains including: Authentication, Scale & Performance, Security & Compliance, Real-Time Features, File & Media, API Design, Search & Discovery, Testing, and Accessibility.
When to Offer Recommendations:
- Inline insights: Brief suggestions during rounds when triggers detected (max 2 per round)
- Recommendations round: Accumulated recommendations presented in Phase 4
- Always present recommendations for user approval — never assume acceptance
Inline Insight Format:
AskUserQuestion:
questions:
- header: "Quick Insight"
question: "{Brief recommendation}. Would you like to include this in the spec?"
options:
- label: "Include this"
description: "Add to spec requirements"
- label: "Tell me more"
description: "Get more details"
- label: "Skip"
description: "Continue without this"
multiSelect: false
For detailed recommendation templates, refer to: references/recommendation-format.md
Tracking Recommendations: Maintain internal tracking of detected triggers and accepted recommendations:
- Detected triggers with source round
- Accepted recommendations with target spec section
- Skipped/modified recommendations
Trigger Detection per Round:
- After receiving user responses, scan for trigger keywords
- Note triggers internally for the recommendations round
- For high-priority triggers (compliance, security), consider inline insight immediately
Codebase Exploration (New Feature Type)
If the product type is "New feature for existing product":
- Read the exploration procedure:
${CLAUDE_PLUGIN_ROOT}/skills/create-spec/references/codebase-exploration.md - Follow all 4 steps (Quick Reconnaissance → Plan Focus Areas → Parallel Exploration → Synthesis)
- After synthesis, store the merged findings internally as "Codebase Context" for use in subsequent interview rounds and spec compilation
- Present a brief summary of key findings to the user before starting the interview
Error handling / fallback: If exploration agents fail (Task tool errors, agent timeouts, etc.):
- If some agents succeeded: continue with partial findings — merge what's available
- If all agents failed: use the reconnaissance findings from Step 1 as minimal context
- If reconnaissance also failed, use
AskUserQuestionto offer fallback:questions: - header: "Fallback" question: "Codebase exploration encountered an issue. How would you like to proceed?" options: - label: "Quick exploration" description: "Fall back to basic Glob/Grep/Read exploration" - label: "Skip" description: "Continue without codebase analysis" multiSelect: false - If quick exploration: use basic Glob/Grep/Read to understand existing patterns, related features, integration points, and data models
- If skip: continue to Phase 3 Round 1 with whatever findings were gathered
Using Exploration Findings in Interview
When codebase exploration was performed (deep or quick), use the findings throughout the interview:
- Tailor technical questions — Reference specific files, patterns, and conventions discovered during exploration
- Skip answered questions — If exploration already revealed tech stack, data models, or architecture, confirm rather than ask open-ended questions
- Ask targeted integration questions — e.g., "The codebase uses {pattern X} for similar features. Should this feature follow the same pattern?"
- Surface risks early — If exploration found challenges (tight coupling, missing tests, complex dependencies), ask about acceptable trade-offs
- Inform recommendations — Use exploration findings as evidence for recommendations in Phase 4
Store findings internally as "Codebase Context" and reference throughout interview and spec compilation.
External Research
Research can be invoked in two ways: on-demand when the user requests it, or proactively for specific high-value topics.
On-Demand Research
When the user explicitly requests research about technologies or general topics during the interview, invoke the research agent.
Technical research triggers:
- "Research the {API/library} documentation"
- "Look up what {technology} supports"
- "Check the docs for {feature}"
- "What does {library} provide for {feature}?"
General topic research triggers:
- "Research best practices for {area}"
- "How do competitors handle {feature}?"
- "What are the industry standards for {area}?"
- "Research {compliance} requirements" (GDPR, HIPAA, WCAG, etc.)
- "Help me understand the problem space for {domain}"
- "What do users expect from {feature type}?"
Proactive Research
You MAY proactively research (without explicit user request) for specific high-value topics:
Auto-research triggers:
- Compliance mentions: GDPR, HIPAA, PCI DSS, SOC 2, WCAG, ADA compliance
- User uncertainty: "I'm not sure", "what do you recommend?", "what's standard?"
- Complex trade-offs: When multiple valid approaches exist and current information would help
Proactive research limit: Maximum 2 proactive research calls per interview to avoid slowing down the process.
Before proactive research, briefly inform the user:
Since you mentioned GDPR compliance, let me quickly research the current requirements to ensure we capture them accurately.
Invoking Research
Use the Task tool with subagent_type researcher:
Task prompt template:
"Research {topic} for spec '{spec_name}'.
Context: {What section of the spec this relates to}
Depth level: {high-level/detailed/full-tech}
Specific questions:
- {Question 1}
- {Question 2}
Return findings in spec-ready format."
Incorporating Research Findings
After receiving research results:
-
Add to interview notes under the appropriate category:
- Technical findings → Technical Specifications
- Best practices → Functional Requirements
- Compliance → Non-Functional Requirements
- Competitive → Problem Statement / Solution Overview
-
Use findings for recommendations: Research-backed recommendations are more valuable; include source attribution
-
Use findings to ask informed follow-ups: Research may reveal new areas to explore
-
Credit sources: Include research sources in spec references section
Tracking Research Usage
Track proactive research usage during the interview:
Proactive Research: 1/2 used
- [Round 2] GDPR requirements - informed compliance recommendation
Early Exit
If the user indicates they want to wrap up early (signals like "I think that's enough", "let's wrap up", "that covers it", "skip the rest"), handle it gracefully:
- Acknowledge the request
- Present a truncated summary of what was gathered so far using the Pre-Compilation Summary format (Phase 5)
- Use
AskUserQuestionto confirm:questions: - header: "Early Completion" question: "Here's what I've gathered so far. Should I generate the spec with this information, or would you like to add anything?" options: - label: "Generate spec" description: "Proceed with what we have" - label: "Add more" description: "I want to provide additional details" multiSelect: false - If generating, add
**Status**: Draft (Partial)to the spec metadata to indicate incomplete coverage - Proceed to Phase 6 (Spec Compilation)
Phase 4: Recommendations Round
After completing the main interview rounds and before the summary, present a dedicated recommendations round.
When to Include
- Skip for high-level depth: High-level specs focus on problem/goals; recommendations may be premature
- Include for detailed/full-tech: These depths benefit from architectural and technical recommendations
- Skip if no triggers detected: If no recommendation triggers were found, proceed directly to Phase 5
Recommendation Categories
Present recommendations organized by category:
- Architecture: Patterns, scaling approaches, data models
- Security: Authentication, encryption, compliance
- User Experience: Accessibility, performance, error handling
- Operational: Monitoring, deployment, testing strategies
Presentation Format
Introduce the recommendations round briefly:
Based on what you've shared, I have a few recommendations based on industry best practices.
I'll present each for your review — you can accept, modify, or skip any of them.
Then present each recommendation using AskUserQuestion:
AskUserQuestion:
questions:
- header: "Recommendation {N} of {Total}: {Category}"
question: "{Recommendation}\n\n**Why this matters:**\n{Brief rationale}"
options:
- label: "Accept"
description: "Include in spec"
- label: "Modify"
description: "Adjust this recommendation"
- label: "Skip"
description: "Don't include"
multiSelect: false
Handling Modifications
If user selects "Modify":
- Ask what they'd like to change using
AskUserQuestion - Present the modified recommendation for confirmation
- Add the modified version to accepted recommendations
Tracking
After the recommendations round, update internal tracking:
- Mark each recommendation as accepted, modified, or skipped
- Note the target spec section for accepted recommendations
- Modified recommendations include the user's adjustments
Phase 5: Pre-Compilation Summary
Before compilation, present a comprehensive summary:
## Requirements Summary
### Problem & Goals
- Problem: {summarized problem statement}
- Success Metrics: {list metrics}
- Primary User: {persona description}
- Business Value: {why this matters}
### Functional Requirements
{List each feature with acceptance criteria}
### Technical Specifications
- Tech Stack: {choices or constraints}
- Integrations: {systems to integrate with}
- Performance: {requirements}
- Security: {requirements}
### Implementation
- Phases: {list phases}
- Dependencies: {list dependencies}
- Risks: {list risks}
- Out of Scope: {list exclusions}
### Agent Recommendations (Accepted)
*The following recommendations were suggested based on industry best practices and accepted during the interview:*
1. **{Category}**: {Recommendation title}
- Rationale: {Why this was recommended}
- Applies to: {Which section/feature}
{Continue for all accepted recommendations, or note "No recommendations accepted" if none}
### Open Questions
{Any unresolved items}
Important: Clearly distinguish the "Agent Recommendations" section from user-provided requirements. This transparency helps stakeholders understand which requirements came from the user versus agent suggestions.
Then use AskUserQuestion to confirm:
questions:
- header: "Summary Review"
question: "Is this requirements summary accurate and complete?"
options:
- label: "Yes, proceed to spec"
description: "Summary is accurate, generate the spec"
- label: "Needs corrections"
description: "I have changes or additions"
multiSelect: false
If user selects "Needs corrections", ask what they'd like to change using AskUserQuestion, then update the summary and confirm again.
Never skip the summary confirmation step. Only proceed to compilation after user explicitly confirms via AskUserQuestion.
Phase 6: Spec Compilation
Template Selection
Choose the appropriate template based on depth level:
| Depth Level | Template | Use Case |
|---|---|---|
| High-level overview | references/templates/high-level.md |
Executive summaries, stakeholder alignment, initial scoping |
| Detailed specifications | references/templates/detailed.md |
Standard development specs with clear requirements |
| Full technical documentation | references/templates/full-tech.md |
Complex features requiring API specs, data models, architecture |
Files in this skill
6create-spec skill questions
How do I install the create-spec skill in Claude Code?
Run npx degit sequenzia/agent-alchemy/claude/sdd-tools/skills/create-spec ~/.claude/skills/create-spec. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the create-spec skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does the skill handle existing context or files?
The skill can ingest file paths or inline text to inform the interview. It uses this context to ask more targeted questions and probe areas not covered in the provided text.
Can the skill be used during a planning phase?
Yes, the skill is designed to generate the spec document itself as the planning activity, rather than creating an implementation plan for the spec.