Spec Kit

A plug-and-play framework for VS Code Copilot agents. Ships 13 agent modes, 6 behavioral weights, 280 workflow skills, and 3 templates.

Prerequisites

• Node.js 18+ — Download from nodejs.org (includes npm and npx)
• VS Code with GitHub Copilot extension

Quick Start

Method 1: npx (easiest — works on Windows, Mac, Linux)

npx create-spec-kit

Method 2: Git clone (works offline, no npm needed after clone)

git clone https://github.com/dhanishtaa-atos/spec-kit.git
cd spec-kit
node bin/create-spec-kit.js ../your-project

Method 3: Windows — if PowerShell blocks npx

REM Use CMD (not PowerShell) and run:
setup.cmd C:\path\to\your\project

REM Or bypass PowerShell execution policy:
powershell -ExecutionPolicy Bypass -File setup.ps1 -TargetDir "C:\path\to\your\project"

REM Or call npx.cmd directly:
"C:\Program Files\nodejs\npx.cmd" create-spec-kit

Method 4: Mac/Linux

chmod +x setup.sh
./setup.sh ~/your-project

Troubleshooting

"Node.js is not installed" / "node is not recognized"

Install Node.js 18+ from nodejs.org. The LTS version is recommended. After install, restart your terminal so node, npm, and npx are on your PATH.

"npx.ps1 cannot be loaded because running scripts is disabled"

PowerShell's execution policy is blocking npx. Fix with any of these:

# Option A: Use CMD instead of PowerShell
cmd /c "npx create-spec-kit"

# Option B: Bypass execution policy for this session
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
npx create-spec-kit

# Option C: Use npx.cmd directly (bypasses .ps1)
& "C:\Program Files\nodejs\npx.cmd" create-spec-kit

# Option D: Use the setup.cmd batch file (if cloned from git)
.\setup.cmd

"ETIMEDOUT" / "network request to registry.npmjs.org failed"

This is a network/proxy issue, not a package problem. Try:

# Check connectivity
npm ping

# If behind a corporate proxy, set it:
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# Increase timeout (package is ~40MB)
npm config set fetch-timeout 120000

# Or skip npx entirely — clone from GitHub:
git clone https://github.com/dhanishtaa-atos/spec-kit.git
cd spec-kit
node bin/create-spec-kit.js ../your-project

"npm ERR! 403 Forbidden" when installing

Your network may block the npm registry. Use the Git clone method instead.

Skills don't show up in VS Code Copilot

1. Make sure files are inside .github/ at the root of your project
2. Restart VS Code after scaffolding
3. Check that GitHub Copilot extension is active

What Gets Installed

your-project/
├── .github/
│   ├── copilot-instructions.md          ← Bootstrap + auto-dispatch rules
│   ├── agents/                          ← 13 agent modes
│   │   ├── godmode.agent.md             ← Full pipeline: brainstorm → plan → execute → verify
│   │   ├── council.agent.md             ← Multi-perspective deliberation (4-6 archetypes)
│   │   ├── sceptic.agent.md             ← Adversarial read-only review
│   │   ├── oracle.agent.md              ← What-if scenario branching
│   │   ├── debug.agent.md               ← Root-cause-first investigation
│   │   ├── tdd.agent.md                 ← Test-driven development enforcer
│   │   ├── review.agent.md              ← Security-focused code review
│   │   ├── brainstorm.agent.md          ← Idea-to-design pipeline
│   │   ├── checkpoint.agent.md          ← Selective autonomy with feedback
│   │   ├── verify.agent.md              ← Evidence-based completion gate
│   │   ├── unstuck.agent.md             ← Problem-solving dispatch
│   │   ├── parallel.agent.md            ← Independent task distribution
│   │   └── defense.agent.md             ← Multi-layer validation
│   ├── instructions/                    ← 6 behavioral weights
│   │   ├── security.instructions.md     ← Safety, refusal logic, OWASP
│   │   ├── compliance.instructions.md   ← Copyright, evenhandedness
│   │   ├── engineering.instructions.md  ← Code gen, testing, commits
│   │   ├── reasoning.instructions.md    ← Search decisions, tool scaling
│   │   ├── persona.instructions.md      ← Tone, formatting, wellbeing
│   │   └── identity.instructions.md     ← Model capabilities, boundaries
│   └── skills/                        ← 280 workflow skills
│       ├── consciousness-council/       ← Multi-archetype deliberation
│       ├── systematic-debugging/        ← Root cause methodology
│       ├── test-driven-development/     ← Red-green-refactor
│       ├── differential-review/         ← Security code review
│       ├── brainstorming/               ← Idea-to-design pipeline
│       ├── scanpy/                      ← Single-cell RNA-seq analysis
│       ├── pytorch-lightning/           ← Deep learning training
│       ├── polars/                      ← Fast dataframe operations
│       ├── rdkit/                       ← Computational chemistry
│       ├── nextflow/                    ← Bioinformatics pipelines
│       └── ... (280 total)              ← Full domain library
└── templates/                           ← Create your own
    ├── skill_template.md                ← New skill boilerplate
    ├── instructions_template.md         ← New instruction set boilerplate
    └── agent_template.md               ← New agent mode boilerplate

How It Works

Agent Modes (.github/agents/)

Show up in the @ agent picker in Copilot Chat. Each has enforced tool restrictions:

| Agent | Tools | Can Edit? | |-------|-------|-----------| | @godmode | Everything | Yes | | @sceptic | read, search | No | | @review | read, search | No | | @verify | read, execute | No | | @tdd | read, edit, execute, search | Yes |

Behavioral Weights (.github/instructions/)

Load automatically based on applyTo patterns:

• security, compliance, persona → Always loaded (applyTo: "**")
• engineering → Only when editing code files
• reasoning, identity → On-demand (matched by description)

Skills (.github/skills/ — 280 skills)

Auto-discovered when description matches the current task. Invoke manually with /skill-name. Covers: software engineering, debugging, security, bioinformatics, data science, ML/AI, scientific computing, chemistry, genomics, visualization, and more.

Creating Your Own

New Skill

# 1. Copy template
Copy-Item templates/skill_template.md .github/skills/my-skill/SKILL.md

# 2. Edit: Change name, description, process, success criteria
# 3. Done — Copilot discovers it automatically

New Instruction Set

Copy-Item templates/instructions_template.md .github/instructions/my-rules.instructions.md
# Edit: Set description, applyTo pattern, add your rules

New Agent Mode

Copy-Item templates/agent_template.md .github/agents/my-agent.agent.md
# Edit: Set description, tools list, persona, constraints

Design Principles

Based on patterns from InstructionsAndSkills:

• Instructions define how an agent behaves — tone, rules, constraints
• Skills define what an agent can do — reusable task workflows
• Agents combine both — persona + tools + restrictions
• Success Criteria in every primitive — clear definition of done
• Constraints in every primitive — explicit boundaries
• Decision-Making Guidelines — how to handle ambiguity

Sources

• Commands: Distilled from Claude Skills community library (200+ skills)
• Weights: Derived from publicly available Fable 5 system prompt analysis (fable5.dev, GitHub Blog)
• Templates: Based on InstructionsAndSkills best practices
• Structure: Follows VS Code Copilot customization primitives

License

MIT