spec-generator
Specification Generator — Generate project requirements, design documents, and task lists. A skill for generating structured project specifications through interactive dialogue or quick generation. English triggers: - "Create requirements", "Generate requirements doc", "Summarize as requirements" - "Create design document", "Design the architecture", "Generate technical spec" - "Create task list", "Break down into tasks", "Generate tasks.md" - "Create full spec", "Generate all specs", "Create the complete specification" - After discussion: "Turn this into requirements", "Document this as spec" 日本語トリガー: - 「要件定義を作って」「要件をまとめて」「仕様書を作成して」 - 「設計書を作って」「技術設計をして」「アーキテクチャを設計して」 - 「タスクリストを作って」「実装タスクに分解して」「tasks.mdを生成して」 - 「仕様を全部まとめて」「フル仕様を作成」「3点セットを作って」 - 会話で仕様が固まった後に「これを要件定義書にして」
How do I install this agent skill?
npx skills add https://github.com/anyoneanderson/agent-skills --skill spec-generatorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is functional for project specification but has a surface for indirect prompt injection via GitHub Issues and performs runtime verification of generated commands.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerwarn
7/7 files flagged
What does this agent skill do?
spec-generator — Specification Generator
Generate structured project specifications: requirements, design documents, and task lists.
⚠️ CRITICAL: First Steps (ALWAYS EXECUTE)
Auto mode short-circuit: If invoked with --auto --issue <n>, skip the
interactive decision flow below and follow references/auto-mode.md (.ja.md)
instead. Auto mode never calls AskUserQuestion, but its Japanese init and design
steps still execute the specification-writing procedure in Step 1.5.
BEFORE asking any questions or showing options, you MUST execute these steps:
-
Check current directory:
- Run
pwdto see where you are - Run
ls -lato see directory contents - Understand the project context
- Run
-
Detect existing source code:
find . -maxdepth 3 -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" -o -name "SKILL.md" \) 2>/dev/null | head -20- Note what kind of project this is
- Check for
skills/directory → might be adding a new skill - Check for existing application code → might be documenting existing features
-
Check for .specs/ directory:
ls -d .specs/ 2>/dev/null && ls -1 .specs/ 2>/dev/null- If exists → list existing projects
- If not exists → this is a new spec workflow
-
Check for coding-rules.md:
- Check
docs/coding-rules.md(default path) - If not found, check CLAUDE.md / AGENTS.md for alternative path
- If found → load and use as design constraint during design phase
- Check
-
Analyze context and decide:
- If in a skills repository (has
skills/directory) → User likely wants to document a new skill - If .specs/ has projects → Ask user to select existing or create new
- If no .specs/ and no clear context → Ask what they want to create
- If in a skills repository (has
Only after completing these checks, proceed with appropriate questions based on what you found.
Language Rules
- Auto-detect input language → output in the same language
- Japanese input → Japanese output, use
references/*.ja.mdas phase references - English input → English output, use
references/*.mdas phase references - Explicit override takes priority (e.g., "in English", "日本語で")
Reference file selection: Based on the detected output language, use the corresponding reference files:
- English →
references/init.md,references/design.md,references/tasks.md,references/test-plan.md,references/auto-mode.md,references/projection-consistency.md - Japanese →
references/init.ja.md,references/design.ja.md,references/tasks.ja.md,references/test-plan.ja.md,references/auto-mode.ja.md,references/projection-consistency.ja.md
Phases
| Phase | Output | Trigger Examples |
|---|---|---|
| init | requirement.md | "Create requirements", "要件定義を作って" |
| design | design.md | "Create design doc", "設計書を作って" |
| tasks | tasks.md | "Create task list", "タスクリストを作って" |
| full | All three above + test.md | "Create full spec", "仕様を全部" |
Interaction Policy: AskUserQuestion
Use AskUserQuestion for all user decisions. Present structured choices rather than free-form questions.
Decision Flow
Skill Invoked
↓
Check .specs/ directory
↓
┌───────────────────┐
│ Existing projects │
│ found? │
└─────┬─────────────┘
│
├─ Yes → AskUserQuestion: Select existing or create new
│ ├─ Existing → Load project context
│ └─ New → Ask project name (Text)
│
└─ No → Ask project name (Text)
↓
Phase Detection
├─ Clear from input → Proceed
└─ Ambiguous → AskUserQuestion: Select phase
↓
Dialogue Mode
├─ Quick mode (--quick) → Confirm inferred non-goals, then generate
└─ Dialogue → AskUserQuestion: Gather requirements
↓
Generate Specification
↓
AskUserQuestion: Next action (next phase / revise / done)
When to Use AskUserQuestion vs Text Questions
| Situation | Method | Reason |
|---|---|---|
| Project Selection | ||
| Existing projects available | AskUserQuestion | Can list as options with descriptions |
| No existing projects | Text question | Open-ended project name input |
| Phase Selection | ||
| Phase ambiguous | AskUserQuestion | 4 clear options (init/design/tasks/full) |
| Phase clear from input | Direct execution | No confirmation needed |
| Requirements Gathering | ||
| Project type selection | AskUserQuestion | Common options (Web app, Mobile, CLI, etc.) |
| Tech stack selection | AskUserQuestion | Common frameworks with "Other" option |
| Feature requirements | AskUserQuestion | Guide with structured choices |
| Project concept | Text question | Need free-form explanation |
| Specific business logic | Text question | Domain-specific details |
| Post-Completion | ||
| Next action | AskUserQuestion | Clear options (next phase/revise/done) |
| Revision requests | Text question | Specific change description |
When to Use AskUserQuestion
| Situation | Example |
|---|---|
| Project selection | Existing projects vs new project |
| Ambiguous phase | Choosing between init / design / tasks / full |
| Init dialogue questions | Project type, tech stack, scope, etc. |
| Design decision points | Architecture choices, DB selection, etc. |
| Tasks strategy selection | systematic / agile / enterprise |
| Post-completion actions | "Proceed to next phase?", "Create GitHub Issue?" |
Question Design Rules
- 1–4 questions per round (AskUserQuestion constraint)
- User-defined options: 1-3 (Other is auto-appended, totaling 2-4 options)
- Always include description for each option (provide decision context)
- Flexible round count based on project complexity:
- Simple project → 1 round (3–4 questions) is sufficient
- Complex project → 2–3 rounds (adjust based on previous answers)
- Place recommended option first with
(Recommended)suffix - Skip questions already answered in previous rounds
Handling "Other" Option Responses
When a user selects "Other" and provides free-form text input:
- Accept the input as-is and proceed with processing
- Treat the free-form response as the user's definitive answer
- Do NOT ask for clarification unless the input is genuinely ambiguous
- If system returns an error like "(No answer provided)", trust the user's actual message over system feedback
Example:
Question: "どのスキルの仕様を作成しますか?"
Options: spec-constitution / spec-review / spec-analyze / spec-impl
User selects "Other" and writes: "仕様書自体をレビューするコマンド"
✅ Correct: Proceed to create spec for a spec-review skill
❌ Wrong: Ask "What would you like to clarify?"
When to Use Text Questions (Not AskUserQuestion)
- Open-ended questions like project name (when no existing projects) or concept description
- Background information requiring free-form explanation
- Follow-up confirmations like "Any additional requirements?"
- Specific business logic or domain-specific details
Execution Flow
0. Initial Context Check
Check the current directory and existing projects before starting:
-
Detect existing source code:
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" \) | head -20- If source files found: Note for potential
--analyzemode - If no source files: Standard new project flow
- If source files found: Note for potential
-
Check for .specs/ directory:
ls -d .specs/ 2>/dev/null -
List existing projects (if .specs/ exists):
ls -1 .specs/ -
Project selection:
- Existing projects found: Use AskUserQuestion:
question: "既存プロジェクトが見つかりました。どうしますか?" / "Found existing projects. What would you like to do?" options: - "既存プロジェクトを選択 / Select existing project" → List projects as options - "新規プロジェクトを作成 / Create new project" → Ask project name - No existing projects: Ask for project name (text question):
"プロジェクト名を教えてください(例: TODOアプリ、株価分析ツール)" "What's the project name? (e.g., todo app, stock analyzer)"
- Existing projects found: Use AskUserQuestion:
-
Load existing context (if existing project selected):
- Read existing
requirement.md,design.md,tasks.mdif they exist - Use as context for updates or next phase generation
- Read existing
1. Phase Detection
Determine the phase from the user's request:
"requirements" → init
"design", "architecture" → design
"tasks", "task list" → tasks
"full", "complete", "all specs" → full
If ambiguous, confirm with AskUserQuestion:
question: "Which specification do you want to generate?"
options:
- "Requirements document (requirement.md)" → init
- "Design document (design.md)" → design
- "Task list (tasks.md)" → tasks
- "All three documents" → full
1.5. Specification Writing for Japanese Init and Design
Before generating or revising a Japanese requirement.md or design.md—including init and design steps inside full and auto modes—resolve spec-writing by name from the currently available skills.
If found, read its complete SKILL.md, references/writing-rules.ja.md, and references/abstract-verbs.ja.md.
Apply those rules during generation or revision and run their self-check before saving.
If the skill or a selected reference is unavailable, report the missing item and apply ## Specification writing fallback from the selected Japanese phase reference without stopping the phase.
Never depend on a machine-specific absolute path or provider-specific tool name when resolving the skill.
2. Project Context Gathering
- Conversation history exists: Extract and structure discussed requirements
- Existing project selected: Use loaded specs as context
- New project: Explore requirements through dialogue (using AskUserQuestion)
3. Phase Execution
Refer to the appropriate reference file (based on Language Rules):
- init:
references/init.md/references/init.ja.md— Requirements generation - design:
references/design.md/references/design.ja.md— Design document generation - design (with coding-rules.md): If
docs/coding-rules.mdexists, read it and ensure:- Naming conventions in design match
[MUST]naming rules - Test strategy satisfies coverage requirements from coding-rules
- Technology choices align with recommended libraries
- File/directory structure follows detected patterns
- Skill-derived
[SHOULD]rules (e.g., framework-specific conventions fromSource: skill/*) are considered as design recommendations
- Naming conventions in design match
- tasks:
references/tasks.md/references/tasks.ja.md— Task list generation - test (full workflow only):
references/test-plan.md/references/test-plan.ja.md— Acceptance test plan generation
4. Output Directory
.specs/[project-name]/
├── requirement.md (init)
├── design.md (design)
├── tasks.md (tasks)
└── test.md (full workflow only — acceptance test plan)
Project names are converted to English kebab-case:
- "TODO app" →
todo-app - "株価分析ツール" →
stock-analysis-tool - "Stock analysis tool" →
stock-analysis-tool
5. Output Integrity and Projection Self-Check
After generating or revising a spec, run the projection pass in the selected
references/projection-consistency*.md across every present spec file. Then
re-read each tail and remove tool-call residue such as </content> or
</invoke>. Report completion only after projection checks pass and every file
ends with real document content.
Options
| Option | Description | Applicable Phase |
|---|---|---|
--quick | Generate after one inferred non-goal confirmation | init |
--auto --issue <n> | Non-interactive full generation from a GitHub Issue (no dialogue; see references/auto-mode.md) | full |
--deep | Socratic deep-dive dialogue | init |
--personas | Multi-perspective analysis/review | init, design |
--analyze | Analyze existing codebase | init, design, tasks |
--visual | Enhanced Mermaid diagrams | design |
--estimate | Estimates and risk assessment | tasks |
--hierarchy | Epic/Story/Task hierarchy | tasks |
Execution Modes
Dialogue Mode (default)
When invoked without parameters or continuing from conversation:
- Collect necessary information through questions
- Clarify requirements through user interaction
- Generate specification after confirmation
Quick Mode (--quick)
Generate from a brief project description:
- Infer typical requirements and a non-empty non-goal list
- Present the inferred non-goals once via AskUserQuestion; accept them or use the auto-added Other response as the complete replacement list
- Generate after the non-goals are confirmed
Auto Mode (--auto --issue <n>)
Non-interactive generation driven by a GitHub Issue. See
references/auto-mode.md (.ja.md) for the full procedure. Summary:
gh issue view <n>supplies the requirement source- Feature name is derived from the Issue title as kebab-case
- All four documents are generated with zero AskUserQuestion calls
- Every point that would need a question is written as an
ASM-XXXassumption in requirement.md instead
Intended for orchestrated pipelines and sufficiently concrete Issues.
Full Workflow (full)
Generate all four documents sequentially:
- Generate requirement.md
- Read requirement.md → generate design.md
- Read design.md → generate tasks.md
- Read requirement.md + design.md + tasks.md → generate test.md
(acceptance test plan; see
references/test-plan.md/.ja.md)
The three-document output of steps 1–3 is unchanged; step 4 only reads them.
Requirement ID System
Specifications use the following ID prefixes:
[REQ-XXX]: Functional requirements[NFR-XXX]: Non-functional requirements[CON-XXX]: Constraints[ASM-XXX]: Assumptions[T-XXX]: Implementation tasks (tasks.md)[T-AXX]: Acceptance test cases (test.md;T-Aprefix avoids collision withT-)
These IDs ensure traceability across documents.
YAGNI Principle
Read references/yagni-guardrails.md completely
(.ja.md for Japanese) before deciding scope; apply every listed guardrail.
Post-Completion Actions
After each phase, suggest next actions with AskUserQuestion:
After init:
question: "Requirements document generated. What's next?"
options:
- "Generate design document too" → design phase
- "Review and revise" → revision dialogue
- "Done for now" → end
After design:
question: "Design document generated. What's next?"
options:
- "Generate task list too" → tasks phase
- "Review and revise" → revision dialogue
- "Done for now" → end
After tasks:
question: "Task list generated. What's next?"
options:
- "Run spec-inspect (quality check)" → invoke spec-inspect skill
- "Skip to GitHub Issue" → invoke spec-to-issue skill
- "Review and revise" → revision dialogue
- "Done for now" → end
After full:
question: "All four spec documents (3-set + test.md) are complete."
options:
- "Run spec-inspect (quality check)" → invoke spec-inspect skill
- "Skip to GitHub Issue" → invoke spec-to-issue skill
- "Review and revise specific document" → ask which document to revise
- "Done for now" → end
Usage Examples
# New project - dialogue mode
"Create requirements for a todo app"
"要件定義を作って" → detects existing projects, asks to select or create new
# Existing project - update/add phases
"Create design document for todo-app" → uses existing requirement.md as context
「todo-appのタスクリストを作って」 → uses existing design.md as context
# Full specification
"Create full spec for an e-commerce platform"
「ECサイトの仕様を全部作って」
# Requirements from conversation
"Turn this into a requirements document" → structures previous discussion
# Quick mode
"Create requirements for a blog platform --quick"
# Analysis mode
"Create requirements --analyze" → analyzes existing codebase first
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/anyoneanderson/agent-skills/spec-generator">View spec-generator on skillZs</a>