spec-writing

Linaqruf 的头像作者 Linaqruf

Use when the user wants to create project specs, design systems, or feature plans. Triggers on "create spec", "plan project", "design system", "plan feature", or "write specification".

📖 中文导读:Use when the user wants to create project specs, design systems, or feature plans. Triggers on "create spec", "plan project", "design system", "plan feature", or "write specification". 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: spec-writing description: Use when the user wants to create project specs, design systems, or feature plans. Triggers on "create spec", "plan project", "design system", "plan feature", or "write specification". version: 3.0.0

Spec Writing v3.0

Generate comprehensive project specifications with SPEC.md as the core file and optional supplements for reference material.

Core Principle

SPEC.md is always the complete spec. SPEC/ files are optional lookup supplements.

SPEC.md               # Always created, always self-sufficient
CLAUDE.md             # Generated with spec references

SPEC/                 # Optional, created when user agrees
├── api-reference.md  # Lookup: endpoint schemas, request/response
├── sdk-patterns.md   # Lookup: external SDK usage patterns
└── data-models.md    # Lookup: complex entity schemas

Key distinction:

  • SPEC.md = Things you READ (narrative, decisions, requirements)
  • SPEC/*.md = Things you LOOK UP (schemas, SDK patterns, external API details)

Single Adaptive Flow

One interview flow replaces previous Quick/SPEC/DEEP modes:

Interview starts
    ↓
Build SPEC.md progressively
    ↓
Hit reference-heavy topic? ──→ Ask: "Create SPEC/[topic].md for lookup?"
    ↓                                    ↓
Continue interview                  User decides (yes/no)
    ↓
Generate SPEC.md + CLAUDE.md
    ↓
If user said yes → Generate SPEC/[topic].md files

Interview Workflow

Phase 1: Vision & Problem

  • Problem statement
  • Target users
  • Success criteria

Phase 2: Requirements

  • MVP features (must-have)
  • Out of scope (explicit)
  • User flows

Phase 3: Architecture

  • System type detection
  • Architecture pattern (present 2-3 alternatives with tradeoffs)
  • Tech stack with recommendations

Phase 4: Tech Stack Details

  • Frontend (if applicable)
  • Backend (if applicable)
  • Database (if applicable)
  • Use multiple choice with recommendations

Phase 5: Design & Security

  • Visual design (if frontend)
  • Authentication approach
  • Constraints & compliance

Supplement Prompts (Mid-Interview)

When hitting reference-heavy topics, ask:

"Your API has 15 endpoints with detailed schemas. Should I:

  • A) Keep it inline in SPEC.md (shorter reference section)
  • B) Create SPEC/api-reference.md as a separate lookup file"

Create supplements only for:

  • Reference material - Stuff you look up, not read through
  • External dependencies - SDK docs, library patterns, third-party APIs

Opinionated Recommendations

Lead with recommended options, allow override:

Which package manager?

- A) bun (Recommended) - Fastest, built-in test runner, drop-in npm replacement
- B) pnpm - Fast, strict dependency resolution, good for monorepos
- C) npm - Universal compatibility, no setup needed
- D) yarn - If team already uses it

Principles:

  1. Lead with recommended option + brief rationale
  2. Context-aware (desktop app? acknowledge Tauri vs Electron tradeoffs)
  3. Acknowledge "it depends" cases (team familiarity, existing codebase)
  4. Stay current with ecosystem changes

SPEC.md Structure

# [Project Name]

## Overview
Problem, solution, target users, success criteria.

## Product Requirements
Core features (MVP), future scope, out of scope, user flows.

## Technical Architecture
Tech stack (with rationale), system design diagram, data models, API endpoints.

## System Maps
- Architecture diagram (ASCII)
- Data model relations
- User flow diagrams
- Wireframes (key screens)

## Design System
(If frontend) Colors, typography, components, accessibility.

## File Structure
Project directory layout.

## Development Phases
Phased implementation plan with checkboxes.

## Open Questions
Decisions to make during development.

---

## References
(If supplements exist) Trigger-based links to SPEC/ files.

Connecting SPEC.md to Supplements

When supplements exist, reference them with triggers:

Inline (in relevant sections):

## API Design

**Endpoints overview:**
- `POST /auth/login` - User authentication
- `GET /projects` - List user projects

→ When implementing endpoints, reference `SPEC/api-reference.md` for full request/response schemas.

References section (bottom):

---

## References

→ When implementing API endpoints: `SPEC/api-reference.md`
→ When using Anthropic SDK: `SPEC/sdk-patterns.md`

CLAUDE.md Generation

Agent-optimized pointer file:

# [Project Name]

[One-line description]

## Spec Reference

Primary spec: `SPEC.md`

→ When implementing API endpoints: `SPEC/api-reference.md`
→ When using [SDK/Library]: `SPEC/sdk-patterns.md`

## Key Constraints

- [Critical constraint 1 - surfaced from spec]
- [Critical constraint 2]
- [Out of scope reminder]

## Commands

- `[package-manager] run dev` - Start development
- `[package-manager] run test` - Run tests
- `[package-manager] run build` - Production build

## Current Status

→ Check `SPEC.md` → Development Phases section

Principles:

  • Surface critical constraints directly (prevent missed context)
  • Trigger-based supplement references
  • Short - pointer, not duplication
  • Status points to SPEC.md (single source)

Context7 Integration

After tech choices, fetch relevant documentation:

1. resolve-library-id for each technology
2. query-docs for setup guides and patterns
3. Include insights in relevant spec files

Best Practices

Interview Conduct

  • Multiple choice: Use AskUserQuestion options, not open-ended text
  • 2-3 alternatives: For key decisions, show options with tradeoffs
  • YAGNI: Ruthlessly simplify - "Do we really need this for MVP?"
  • Supplements on demand: Only offer when content is truly reference-heavy

Output Quality

  • Be specific and actionable
  • Include code examples for data models
  • Reference Context7 documentation
  • Keep scope realistic for MVP
  • Include system maps (architecture, data relations, user flows)

Reference Files

Templates

  • references/output-template.md - SPEC.md structure
  • templates/index.template.md
  • templates/overview.template.md
  • templates/architecture.template.md
  • templates/frontend.template.md
  • templates/backend.template.md
  • templates/design-system.template.md
  • templates/api-reference.template.md
  • templates/cli-reference.template.md
  • templates/data-models.template.md
  • templates/security.template.md

References

  • references/interview-questions.md - Question bank with recommendations
  • references/spec-folder-template.md - Supplement structure guide

Examples

  • examples/web-app-spec.md
  • examples/cli-spec.md
  • examples/api-spec.md
  • examples/library-spec.md
  • /spec - Generate project specification
  • /feature - Generate feature specification
  • /design - Generate design system specification
  • /sync - Sync spec with codebase changes (git-aware)

Integration with Other Skills

feature-dev

After creating specs, use feature-dev agents:

  1. code-explorer - Analyze existing patterns
  2. code-architect - Design implementation
  3. code-reviewer - Review implementation

frontend-design

Use design specs to implement components following the specification.