Beginner

Getting Started with spec-kit

Install spec-kit, initialize your first project, and create your first specification document. Learn the CLI commands and understand the spec structure.

Installation

spec-kit is distributed as an npm package. You need Node.js 18+ installed on your system.

Terminal 
# Install globally
npm install -g spec-kit

# Or install as a project dependency
npm install --save-dev spec-kit

# Verify installation
specc --version
✅
Tip: If you install spec-kit as a project dependency (recommended for teams), use npx specc to run commands, or add scripts to your package.json.

Project Initialization

Initialize spec-kit in your project directory to create the specification structure:

Terminal 
# Navigate to your project
cd my-project

# Initialize spec-kit
specc init

# Initialize with options
specc init --template enterprise --ai-provider openai

This creates the following directory structure:

Project Structure 
my-project/
  specs/
    .specc/
      config.yaml        # Configuration file
      templates/          # Custom templates
    prds/                 # Product Requirements Documents
    tech-specs/           # Technical Specifications
    api-specs/            # API Specifications
    adrs/                 # Architecture Decision Records

Creating Your First Spec

Let's create a simple Product Requirements Document:

  1. Create the PRD

    Use the create command to generate a new specification:

Terminal 
# Create a new PRD
specc create prd --name "user-authentication"

# Create with AI-generated content
specc create prd --name "user-authentication" \
  --ai \
  --context "OAuth2 login with Google and GitHub providers"

Understanding Spec Structure

spec-kit uses a combination of YAML frontmatter and Markdown content:

YAML + Markdown 
---
title: User Authentication
type: prd
status: draft
version: 1.0.0
author: jane.doe
created: 2026-03-14
tags:
  - authentication
  - oauth2
  - security
reviewers:
  - john.smith
  - alice.chen
---

# User Authentication

## Overview
Implement OAuth2 authentication supporting Google
and GitHub as identity providers.

## Goals
- Secure user authentication
- Seamless SSO experience
- Support multiple identity providers

## User Stories
- As a user, I want to sign in with my Google
  account so I don't need a new password.

## Acceptance Criteria
- [ ] Users can sign in via Google OAuth2
- [ ] Users can sign in via GitHub OAuth2
- [ ] Session tokens expire after 24 hours

Essential CLI Commands

Here are the most important spec-kit commands to get started:

Command Description
specc init Initialize spec-kit in the current project
specc create <type> Create a new specification (prd, tech-spec, api-spec, adr)
specc generate --ai Generate or expand spec content using AI
specc list List all specifications in the project
specc validate Validate spec structure and completeness
specc export Export specs to Markdown, PDF, or other formats
specc review Submit a spec for team review
specc status Show the status of all specifications
⚠
Important: The --ai flag requires an AI provider API key. Set it via the SPECC_AI_KEY environment variable or in your config.yaml file. Supported providers include OpenAI, Anthropic, and Google.

Configuration

The config.yaml file controls spec-kit behavior:

config.yaml 
project:
  name: my-project
  org: acme-corp

ai:
  provider: anthropic
  model: claude-sonnet

templates:
  directory: .specc/templates

export:
  default_format: markdown
  output_dir: docs/specs

review:
  require_approval: true
  min_reviewers: 1

Ready to Go Deeper?

Live instructor-led courses from our partners. Affiliate disclosure.

🧠

AI & ML Courses - 30% Off

Live instructor-led AI, machine learning, data science, and cloud courses for working professionals. Use code Limited30 at checkout.

Edureka
📊

DataCamp - AI & Data Science

Hands-on Python, machine learning, and AI courses with interactive exercises and real projects.

DataCamp
🎓

edX - Top AI Courses

University-level AI courses from MIT, Harvard, Stanford. Earn certificates that employers recognize.

edX