Agent Skills

Name: Agent Skills
Author: addyosmani

Production-grade engineering skills for AI coding agents.

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

Commands

9 slash commands that map to the development lifecycle. Each one activates the right skills automatically.

What you're doing	Command	Key principle
Define what to build	`/spec`	Spec before code
Plan how to build it	`/plan`	Small, atomic tasks
Build incrementally	`/build`	One slice at a time
Prove it works	`/test`	Tests are proof
Set the quality bar	`/constraints`	Decide it once, enforce it everywhere
Review before merge	`/review`	Improve code health
Audit web performance	`/webperf`	Measure before you optimize
Simplify the code	`/code-simplify`	Clarity over cleverness
Ship to production	`/ship`	Faster is safer

Want fewer manual steps once the spec exists? /build auto generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping between tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.

Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

Quick Start

Fastest path — any agent, one command. The open skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):

npx skills add addyosmani/agent-skills            # install all 25 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

Or grab individual skills:

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced

Installing one skill? A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory. The skill still works, but paths to supplementary shared checklists are unavailable. Use a whole-repo integration, clone the repository, or copy the needed checklist into a references/ directory inside the installed skill. This portability gap is tracked in #361.

Prefer a native integration? Pick your tool below.

<details> <summary>Claude Code (recommended)</summary>

Marketplace install:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

SSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or use the full HTTPS URL to force HTTPS cloning during the marketplace-add step:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills
If /plugin install still fails with git@github.com: Permission denied (publickey) on Windows or macOS, the recommended workaround is to configure Git once to rewrite GitHub SSH URLs to HTTPS for subprocess clones:
git config --global url."https://github.com/".insteadOf git@github.com:

Local / development:

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

</details> <details> <summary>Cursor</summary>

Put workflow skills under .cursor/skills/ (sync from agent-skills/skills/) and short policies in .cursor/rules/*.mdc — do not paste full skills into rules. See docs/cursor-setup.md.

</details> <details> <summary>Antigravity CLI</summary>

Install as a native plugin for skills, subagents, and slash commands. See docs/antigravity-setup.md.

Install from the repo:

agy plugin install https://github.com/addyosmani/agent-skills.git

Install from a local clone:

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

</details> <details> <summary>Gemini CLI</summary>

Install as native skills for auto-discovery, or add to GEMINI.md for persistent context. See docs/gemini-cli-setup.md.

Install from the repo:

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Install from a local clone:

gemini skills install ./agent-skills/skills/

</details> <details> <summary>Windsurf</summary>

Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.

</details> <details> <summary>OpenCode</summary>

Copy skills to .opencode/skills/ (or ~/.config/opencode/skills/), add a project-local AGENTS.md, and use the built-in skill tool for agent-driven execution. Optional slash commands can be added under .opencode/commands/.

See docs/opencode-setup.md.

</details> <details> <summary>GitHub Copilot</summary>

Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.

</details> <details> <summary>Kiro IDE & CLI </summary> Skills for Kiro reside under ".kiro/skills/" and can be stored under Project or Global level. Kiro also supports Agents.md. See Kiro docs at https://kiro.dev/docs/skills/ </details> <details> <summary>Codex</summary>

Install as a native Codex plugin (Codex CLI v0.122+):

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

The first command registers the marketplace; the second installs the plugin. Codex reads the root skills/ directory directly through .codex-plugin/plugin.json. Once installed, invoke skills in chat using @ (e.g., @spec-driven-development). See docs/codex-setup.md for local installation and troubleshooting.

</details> <details> <summary>Command Code</summary>

Install natively with the built-in cmd skills command. Command Code clones the repo, discovers every SKILL.md, and installs into .commandcode/skills/:

cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill

Installed skills show up in the TUI slash menu, e.g. /spec-driven-development. See docs/commandcode-setup.md.

</details> <details> <summary>Other Agents</summary>

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.

</details>

Adoption

Already installed? How you roll the pack out depends on your codebase. The Adoption Guide covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.

All 24 Skills

The commands above are entry points. The pack includes 25 skills total — 24 lifecycle skills plus the using-agent-skills meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.

Meta - Discover which skill applies

Skill	What It Does	Use When
using-agent-skills	Maps incoming work to the right skill workflow and defines shared operating rules	Starting a session or deciding which skill applies

Define - Clarify what to build

Skill	What It Does	Use When
interview-me	One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence	The ask is underspecified, or the user invokes "interview me" / "grill me"
idea-refine	Structured divergent/convergent thinking to turn vague ideas into concrete proposals	You have a rough concept that needs exploration
spec-driven-development	Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code	Starting a new project, feature, or significant change
constraint-driven-development	Interviews you for a quality bar with sane default thresholds, writes CONSTRAINTS.md, places each check by cost, and catches agents silencing checks or skipping tests to get green	No standards are written down, or an agent is producing more than anyone reads

Plan - Break it down

Skill	What It Does	Use When
planning-and-task-breakdown	Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering	You have a spec and need implementable units

Build - Write the code

Skill	What It Does	Use When
incremental-implementation	Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes	Any change touching more than one file
test-driven-development	Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing	Implementing logic, fixing bugs, or changing behavior
context-engineering	Feed agents the right information at the right time - rules files, context packing, MCP integrations	Starting a session, switching tasks, or when output quality drops
source-driven-development	Ground every framework decision in official documentation - verify, cite sources, flag what's unverified	You want authoritative, source-cited code for any framework or library
doubt-driven-development	Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation	Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later
frontend-ui-engineering	Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility	Building or modifying user-facing interfaces
api-and-interface-design	Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation	Designing APIs, module boundaries, or public interfaces

Verify - Prove it works

Skill	What It Does	Use When
browser-testing-with-devtools	Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling	Building or debugging anything that runs in a browser
debugging-and-error-recovery	Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks	Tests fail, builds break, or behavior is unexpected

Review - Quality gates before merge

Skill	What It Does	Use When
code-review-and-quality	Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies	Before merging any change
code-simplification	Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior	Code works but is harder to read or maintain than it should be
security-and-hardening	OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system	Handling user input, auth, data storage, or external integrations
performance-optimization	Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection	Performance requirements exist or you suspect regressions

Ship - Deploy with confidence

Skill	What It Does	Use When
git-workflow-and-versioning	Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern	Making any code change (always)
ci-cd-and-automation	Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops	Setting up or modifying build and deploy pipelines
deprecation-and-migration	Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal	Removing old systems, migrating users, or sunsetting features
documentation-and-adrs	Architecture Decision Records, API docs, inline documentation standards - document the why	Making architectural decisions, changing APIs, or shipping features
observability-and-instrumentation	Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build	Adding telemetry, or shipping anything that runs in production
shipping-and-launch	Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup	Preparing to deploy to production

Agent Personas

Pre-configured specialist personas for targeted reviews:

Agent	Role	Perspective
code-reviewer	Senior Staff Engineer	Five-axis code review with "would a staff engineer approve this?" standard
test-engineer	QA Specialist	Test strategy, coverage analysis, and the Prove-It pattern
security-auditor	Security Engineer	Vulnerability detection, threat modeling, OWASP assessment
web-performance-auditor	Web Performance Engineer	Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via `/webperf`

See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.

Reference Checklists

Quick-reference material that skills pull in when needed:

Reference	Covers
definition-of-done.md	Project-wide standing bar every change clears, contrasted with per-task acceptance criteria
testing-patterns.md	Test structure, naming, mocking, React/API/E2E examples, anti-patterns (JavaScript/TypeScript)
security-checklist.md	Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10
performance-checklist.md	Core Web Vitals targets, frontend/backend checklists, measurement commands
accessibility-checklist.md	Keyboard nav, screen readers, visual design, ARIA, testing tools
observability-checklist.md	On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gate
orchestration-patterns.md	Endorsed multi-persona orchestration patterns, anti-patterns, and the "personas don't invoke personas" rule

How Skills Work

Every skill follows a consistent anatomy:

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│                                                 │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │                                                                                                
│  Overview         → What this skill does        │
│  When to Use      → Triggering conditions       │
│  Process          → Step-by-step workflow       │
│  Rationalizations → Excuses + rebuttals         │
│  Red Flags        → Signs something's wrong     │
│  Verification     → Evidence requirements       │
└─────────────────────────────────────────────────┘

Key design choices:

Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
Progressive disclosure. The SKILL.md is the entry point. Supporting references load only when needed, keeping token usage minimal.

Project Structure

agent-skills/
├── skills/                            # 25 skills (24 lifecycle + 1 meta)
│   ├── interview-me/                  #   Define
│   ├── idea-refine/                   #   Define
│   ├── spec-driven-development/       #   Define
│   ├── constraint-driven-development/ #   Define
│   ├── planning-and-task-breakdown/   #   Plan
│   ├── incremental-implementation/    #   Build
│   ├── context-engineering/           #   Build
│   ├── source-driven-development/     #   Build
│   ├── doubt-driven-development/      #   Build
│   ├── frontend-ui-engineering/       #   Build
│   ├── test-driven-development/       #   Build
│   ├── api-and-interface-design/      #   Build
│   ├── browser-testing-with-devtools/ #   Verify
│   ├── debugging-and-error-recovery/  #   Verify
│   ├── code-review-and-quality/       #   Review
│   ├── code-simplification/           #   Review
│   ├── security-and-hardening/        #   Review
│   ├── performance-optimization/      #   Review
│   ├── git-workflow-and-versioning/   #   Ship
│   ├── ci-cd-and-automation/          #   Ship
│   ├── deprecation-and-migration/     #   Ship
│   ├── documentation-and-adrs/        #   Ship
│   ├── observability-and-instrumentation/ # Ship
│   ├── shipping-and-launch/           #   Ship
│   └── using-agent-skills/            #   Meta: how to use this pack
├── agents/                            # 4 specialist personas
├── references/                        # 7 supplementary checklists
├── hooks/                             # Session lifecycle hooks
├── .claude/commands/                  # 8 slash commands (Claude Code)
├── .gemini/commands/                  # 8 slash commands (Gemini CLI)
├── commands/                          # 8 slash commands (Antigravity CLI)
├── plugin.json                        # Antigravity plugin manifest
└── docs/                              # Setup guides per tool

Why Agent Skills?

AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code.

Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.

Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.

How it compares

Wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md for an honest, side-by-side look at how the three are shaped differently and when to reach for each — including a link to a controlled head-to-head experiment.

Contributing

Skills should be specific (actionable steps, not vague advice), verifiable (clear exit criteria with evidence requirements), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent).

See docs/skill-anatomy.md for the format specification and CONTRIBUTING.md for guidelines.

Team

agent-skills is built and maintained by:

	Name	GitHub	Role
<img src="https://github.com/addyosmani.png?size=120" width="60" height="60" alt="Addy Osmani">	Addy Osmani	@addyosmani	Creator
<img src="https://github.com/federicobartoli.png?size=120" width="60" height="60" alt="Federico Bartoli">	Federico Bartoli	@federicobartoli	Collaborator
<img src="https://

…

using-agent-skills

name: using-agent-skills description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.

Using Agent Skills

Overview

Agent Skills is a collection of engineering workflow skills organized by development phase. Each skill encodes a specific process that senior engineers follow. This meta-skill helps you discover and apply the right skill for your current task.

Skill Discovery

When a task arrives, identify the development phase and apply the corresponding skill:

Task arrives
    │
    ├── Don't know what you want yet? ──────→ interview-me
    ├── Have a rough concept, need variants? → idea-refine
    ├── New project/feature/change? ──→ spec-driven-development
    ├── No quality bar written down? ──→ constraint-driven-development
    ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
    ├── Implementing code? ────────────→ incremental-implementation
    │   ├── UI work? ─────────────────→ frontend-ui-engineering
    │   ├── API work? ────────────────→ api-and-interface-design
    │   ├── Need better context? ─────→ context-engineering
    │   ├── Need doc-verified code? ───→ source-driven-development
    │   └── Stakes high / unfamiliar code? ──→ doubt-driven-development
    ├── Writing/running tests? ────────→ test-driven-development
    │   └── Browser-based? ───────────→ browser-testing-with-devtools
    ├── Something broke? ──────────────→ debugging-and-error-recovery
    ├── Reviewing code? ───────────────→ code-review-and-quality
    │   ├── Too complex? ─────────────→ code-simplification
    │   ├── Security concerns? ───────→ security-and-hardening
    │   └── Performance concerns? ────→ performance-optimization
    ├── Committing/branching? ─────────→ git-workflow-and-versioning
    ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
    ├── Deprecating/migrating? ────────→ deprecation-and-migration
    ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
    ├── Adding logs/metrics/alerts? ───→ observability-and-instrumentation
    └── Deploying/launching? ─────────→ shipping-and-launch

Core Operating Behaviors

These behaviors apply at all times, across all skills. They are non-negotiable.

1. Surface Assumptions

Before implementing anything non-trivial, explicitly state your assumptions:

ASSUMPTIONS I'M MAKING:
1. [assumption about requirements]
2. [assumption about architecture]
3. [assumption about scope]
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The most common failure mode is making wrong assumptions and running with them unchecked. Surface uncertainty early — it's cheaper than rework.

2. Manage Confusion Actively

When you encounter inconsistencies, conflicting requirements, or unclear specifications:

STOP. Do not proceed with a guess.
Name the specific confusion.
Present the tradeoff or ask the clarifying question.
Wait for resolution before continuing.

Bad: Silently picking one interpretation and hoping it's right. Good: "I see X in the spec but Y in the existing code. Which takes precedence?"

3. Push Back When Warranted

You are not a yes-machine. When an approach has clear problems:

Point out the issue directly
Explain the concrete downside (quantify when possible — "this adds ~200ms latency" not "this might be slower")
Propose an alternative
Accept the human's decision if they override with full information

Sycophancy is a failure mode. "Of course!" followed by implementing a bad idea helps no one. Honest technical disagreement is more valuable than false agreement.

4. Enforce Simplicity

Your natural tendency is to overcomplicate. Actively resist it.

Before finishing any implementation, ask:

Can this be done in fewer lines?
Are these abstractions earning their complexity?
Would a staff engineer look at this and say "why didn't you just..."?

If you build 1000 lines and 100 would suffice, you have failed. Prefer the boring, obvious solution. Cleverness is expensive.

5. Maintain Scope Discipline

Touch only what you're asked to touch.

Do NOT:

Remove comments you don't understand
"Clean up" code orthogonal to the task
Refactor adjacent systems as a side effect
Delete code that seems unused without explicit approval
Add features not in the spec because they "seem useful"

Your job is surgical precision, not unsolicited renovation.

6. Verify, Don't Assume

Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).

Per-skill verification is the local check. The project-wide bar that applies to every change, regardless of which skill is active, is the Definition of Done: tests pass, no regressions, behavior verified at runtime, docs updated. See ../../references/definition-of-done.md. It complements each task's acceptance criteria rather than replacing them.

Failure Modes to Avoid

These are the subtle errors that look like productivity but create problems:

Making wrong assumptions without checking
Not managing your own confusion — plowing ahead when lost
Not surfacing inconsistencies you notice
Not presenting tradeoffs on non-obvious decisions
Being sycophantic ("Of course!") to approaches with clear problems
Overcomplicating code and APIs
Modifying code or comments orthogonal to the task
Removing things you don't fully understand
Building without a spec because "it's obvious"
Skipping verification because "it looks right"

Skill Rules

Check for an applicable skill before starting work. Skills encode processes that prevent common mistakes.
Skills are workflows, not suggestions. Follow the steps in order. Don't skip verification steps.
Multiple skills can apply. A feature implementation might involve idea-refine → spec-driven-development → planning-and-task-breakdown → incremental-implementation → test-driven-development → code-review-and-quality → code-simplification → shipping-and-launch in sequence.
When in doubt, start with a spec. If the task is non-trivial and there's no spec, begin with spec-driven-development.

Lifecycle Sequence

For a complete feature, the typical skill sequence is:

1.  interview-me                → Extract what the user actually wants
2.  idea-refine                 → Refine vague ideas
3.  spec-driven-development     → Define what we're building
4.  planning-and-task-breakdown → Break into verifiable chunks
5.  context-engineering         → Load the right context
6.  source-driven-development   → Verify against official docs
7.  incremental-implementation  → Build slice by slice
8.  observability-and-instrumentation → Instrument as you build (runs parallel with 7-9, not after)
9.  doubt-driven-development    → Cross-examine non-trivial decisions in-flight
10. test-driven-development     → Prove each slice works
11. code-review-and-quality     → Review before merge
12. code-simplification         → Reduce unnecessary complexity while preserving behavior
13. git-workflow-and-versioning → Clean commit history
14. documentation-and-adrs      → Document decisions
15. deprecation-and-migration   → Retire old systems and move users safely when needed
16. shipping-and-launch         → Deploy safely

Not every task needs every skill. A bug fix might only need: debugging-and-error-recovery → test-driven-development → code-review-and-quality.

Quick Reference

Phase	Skill	One-Line Summary
Define	interview-me	Surface what the user actually wants before any plan, spec, or code exists
Define	idea-refine	Refine ideas through structured divergent and convergent thinking
Define	spec-driven-development	Requirements and acceptance criteria before code
Plan	planning-and-task-breakdown	Decompose into small, verifiable tasks
Build	incremental-implementation	Thin vertical slices, test each before expanding
Build	source-driven-development	Verify against official docs before implementing
Build	doubt-driven-development	Adversarial fresh-context review of every non-trivial decision
Build	context-engineering	Right context at the right time
Build	frontend-ui-engineering	Production-quality UI with accessibility
Build	api-and-interface-design	Stable interfaces with clear contracts
Verify	test-driven-development	Failing test first, then make it pass
Verify	browser-testing-with-devtools	Chrome DevTools MCP for runtime verification
Verify	debugging-and-error-recovery	Reproduce → localize → fix → guard
Review	code-review-and-quality	Five-axis review with quality gates
Review	code-simplification	Preserve behavior while reducing unnecessary complexity
Review	security-and-hardening	OWASP prevention, input validation, least privilege
Review	performance-optimization	Measure first, optimize only what matters
Ship	git-workflow-and-versioning	Atomic commits, clean history
Ship	ci-cd-and-automation	Automated quality gates on every change
Ship	deprecation-and-migration	Remove old systems and migrate users safely
Ship	documentation-and-adrs	Document the why, not just the what
Ship	observability-and-instrumentation	Structured logs, RED metrics, traces, symptom-based alerts
Ship	shipping-and-launch	Pre-launch checklist, monitoring, rollback plan

interview-me

name: interview-me description: Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.

Interview Me

Overview

What people ask for and what they actually want are different things. They ask for "a dashboard" because that's what one asks for, not because a dashboard solves their problem. They say "make it faster" without a number to hit.

The cheapest moment to find this gap is before any plan, spec, or code exists. Once you've started building, switching costs are real, and the user will rationalize the wrong thing into a "good enough" thing. The misfit gets locked in.

This skill closes the gap before it costs anything. The other Define-phase skills assume you already know roughly what you want: idea-refine generates variations from an idea, spec-driven-development writes the requirements down, doubt-driven-development stress-tests a plan after you've drafted one. Interview-me is the part before all of those, where you ask one question at a time, with your best guess attached, until you can predict what the user is going to say before they say it.

When to Use

Apply this skill when:

The ask is missing at least one of: who the user is, why they want it, what success looks like, what the binding constraint is
The request is conventional rather than specific ("build me X", "make it faster") and you can't unpack the convention without guessing
You're tempted to start with assumptions you haven't surfaced
The user hasn't said which value they're optimizing for when two reasonable ones are in tension (simplicity vs. flexibility, cost vs. speed)
The user explicitly invokes: "interview me", "grill me", "before we start, are we sure?", "stress-test my thinking"

When NOT to use:

The ask is unambiguous and self-contained ("rename this variable", "fix this typo")
The user has explicitly asked for speed over verification
Pure information requests ("how does X work?", "what does this code do?")
Mechanical operations (renames, formats, file moves)
You already have ≥95% confidence; re-read the stop condition below before assuming you don't

Loading Constraints

This skill needs a live, responsive user. Do not invoke in non-interactive contexts like CI pipelines, scheduled runs, /loop, or autonomous-loop. If you're in one of those and the ask is underspecified, flag that as a blocker for the user instead of guessing.

The Process

Step 1: Hypothesize, with a confidence number

Before asking anything, write down your current best read of what the user wants in one sentence, plus an honest confidence number (0–100%):

HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" was the convention that came to mind.
CONFIDENCE: ~30% — missing: who it's for, what "metrics" means in context, and what success looks like

The number forces honesty. If you wrote down a high number but can't actually predict the user's reactions to the next three questions you'd ask, the number is wrong. Start at the confidence level you can defend.

When confidence is below ~70%, append a brief reason on the same line — what's still unresolved or missing. This tells the user exactly what the interview needs to surface, and prevents the number from being a vague signal.

Step 2: Ask one question at a time, each with a guess attached

Format:

Q: <one focused question>
GUESS: <your hypothesis for the answer, with the reasoning that produced it>

Wait for the user to react before asking the next question.

Why one at a time, not a batch:

The user can't react to your hypotheses if you bury them in a list
Batches encourage skim-reading and surface answers
The third question often depends on the answer to the first; asking them all at once locks in the wrong framing
The user's energy for thinking carefully is finite; spend it one question at a time

Why attach a guess:

The user reacts faster to a wrong guess than they generate an answer from scratch
It commits you to a hypothesis you can be visibly wrong about, which keeps you honest
It surfaces your assumptions, which is what the interview is meant to expose

The risk here is a polite user agreeing with your guess to be agreeable. Mitigate by being visibly willing to be wrong, and occasionally guess in a direction you expect the user to push back on.

Step 3: Listen for "want vs. should want"

The most dangerous answers are the ones where the user says what a thoughtful answer sounds like rather than what they actually want. Watch for:

Answers that pattern-match best-practice talk ("I want it to be scalable", "clean architecture") without specifics
Answers that defer to convention ("the way most apps do it", "the standard approach")
Phrases like "I should probably…", "I think I'm supposed to…", "good engineering practice says…"
Buzzwords as goals — when "modern", "scalable", "robust" are the answer instead of a specific outcome

When you hear these, the question to ask is:

"If you didn't have to justify this to anyone, what would you actually want?"

That single question often does more work than the previous five.

Step 4: Restate intent in the user's own words

When your confidence is high, write back what you now think the user wants. Keep it tight (5–8 lines), use their language where possible, and structure it so the user can confirm or correct line by line:

Here's what I now think you want:

- Outcome:      <one line>
- User:         <one line — who benefits>
- Why now:      <one line — what changed>
- Success:      <one line — how we know it worked>
- Constraint:   <one line — the binding limit>
- Out of scope: <one line — what we're explicitly not doing>

Yes / no / refine?

Including "Out of scope" is non-negotiable. Half of misalignment is silent disagreement about what is not being built.

Step 5: Confirm — explicit yes, not "whatever you think"

The gate is an explicit "yes." The following are not yes:

"Whatever you think is best." → The user is delegating, which means they don't have 95% confidence either. Re-ask with two concrete options framed as a choice.
"Sounds good." → Ambiguous. Ask: "Anything you'd refine?" Silence isn't confirmation.
"Sure, let's go." → Often a polite exit, not an endorsement. Same follow-up.
Silence followed by "okay let's start." → The user has given up on the interview, not converged. Stop and ask whether you've missed something.

If they correct you, fold the correction in and restate. Loop until you get an explicit yes.

The 95% Confidence Stop

You're done when you can answer yes to this:

Can I predict the user's reaction to the next three questions I would ask?

If yes, you have shared understanding. Stop interviewing and produce the restate. If no, you're not done; ask the next question.

This is a checkable test, not a vibe. It also has a floor: if you've gone several rounds and still can't predict, that's information about the ask, not a reason to keep grinding. Stop and tell the user: "I've asked X questions and I still can't predict your reactions. Something foundational is missing. Want to step back?"

Output

The output of this skill is a confirmed statement of intent: the restate from Step 4, with an explicit yes from Step 5. That's the deliverable. Specs, plans, and task lists are downstream; they consume the intent this skill produces.

If the user wants the intent to persist (a multi-session project, a handoff to another collaborator), offer to save it to docs/intent/[topic].md. Only save if they confirm.

Example

A short before-and-after.

Without interview-me:

User:  build me a dashboard for our metrics
Agent: <starts proposing chart libraries and layouts>

The agent has assumed: who it's for, what metrics, what "for our team" means, what success looks like. None of these are stated. Every assumption is a place the user can later say "that's not what I meant."

With interview-me:

User: build me a dashboard for our metrics

Agent:
HYPOTHESIS: You want a way to answer "how are we doing?" in standup, and "dashboard" came to mind because that's the conventional answer.
CONFIDENCE: ~30% — missing: who it's for, what "metrics" are, and what success looks like

Q:     When you say "how are we doing?", who's asking — you alone, the engineering team in standup, or up the chain (e.g., your manager, an exec, a board)?
GUESS: engineering team in standup, because "we" usually scopes that way and standups are where this question gets asked. If it's for execs the metrics and the framing change a lot.

User: It's actually for me. I keep losing track of which experiments are running and what their early signal looks like.

Agent:
Updated read: not a team dashboard at all. It's a personal experiment tracker. Confidence: ~60% — still missing: what "early signal" means and what done looks like.

Q:     Is the gap that you don't know which experiments exist, or that you can't see their results in one place?
GUESS: the second one. You have a list of experiments somewhere, but their results live in five different tools, and reconciling them by hand is what you're tired of.

User: First one actually. I literally don't have a list. They're spread across different docs.

Agent: <continues>

Two questions in, the agent has discovered the actual ask isn't "a dashboard." It's "a list." Different artifact, different scope, different work. The dashboard would have been wrong.

Interaction with Other Skills

idea-refine: downstream. If the confirmed intent is "I want X but I don't know how to scope it," hand off to idea-refine to generate variations against the now-explicit intent.
spec-driven-development: downstream. If the confirmed intent is concrete ("I want X for Y users with Z success criteria"), hand off to spec-driven-development to write it down.
planning-and-task-breakdown: two hops downstream of this skill (after the spec).
doubt-driven-development: opposite end of the timeline. Interview-me is pre-decision intent extraction; doubt-driven is post-decision artifact review. Both catch divergence, but at different moments.
source-driven-development: orthogonal. Interview-me clarifies what the user wants; SDD verifies framework facts. They don't compete.

Common Rationalizations

Rationalization	Reality
"The ask is clear enough"	If you can't write the user's desired outcome in one sentence right now, the ask isn't clear. Run Step 1 before deciding.
"Asking too many questions wastes their time"	Time wasted by 4–6 targeted questions is small. Time wasted by building the wrong thing is enormous, and the user is the one bearing that cost.
"I'll figure it out as I build"	Switching costs after code exists are 10x what they are now. Discovery during implementation is rework.
"They said 'whatever you think,' so I should just decide"	"Whatever you think" is delegation, not decision. Re-ask with two concrete options as a choice.
"I should give them several options to pick from"	Options work when the user knows what they want and is choosing between trade-offs. They don't know what they want yet. Listing options widens the search; asking narrows it.
"If I attach my guess, I'm leading them"	Leading is the point. Reacting is faster than generating from scratch. The risk is sycophancy, not leading; mitigate by being visibly willing to be wrong.
"We've talked enough, I get it"	Test it: can you predict their reaction to the next three questions? If not, you don't get it yet.
"The user said yes, we're done"	If the yes followed a vague restate or an open-ended "sounds good," the yes is hollow. Restate concretely and re-confirm.

Red Flags

Three or more questions in a single message: that's batching, not interviewing
A question without your hypothesis attached: that's surveying, not committing
Accepting "whatever you think is best" as a terminal answer
Producing a spec, plan, or task list before the user has explicitly confirmed your restate
Questions framed as "what would be best practice?" instead of "what do you actually want?"
The user gives a sophistication-signaling answer ("scalable", "clean", "modern") and you accept it without probing whether it's what they actually want
Three or more rounds without your confidence visibly rising: you're asking the wrong questions, step back and reframe
A confidence number below ~70% with no reason attached: the user can't help close the gap if they don't know what's missing
Saving the intent doc before the user has confirmed (the doc itself implies a yes the user didn't give)
Skipping the "Out of scope" line in the restate (silent disagreement about non-goals is half of misalignment)

Verification

After applying interview-me:

An explicit hypothesis with a confidence number was stated in the first turn
Every confidence number below ~70% was accompanied by a one-line reason (what's still unresolved or missing)
Questions were asked one at a time, each with the agent's guess attached
At least one "what would you actually want if you didn't have to justify it?" probe ran when the user gave a sophistication-signaling or convention-signaling answer
A concrete restate (Outcome / User / Why now / Success / Constraint / Out of scope) was written back to the user
The user confirmed the restate with an explicit yes (not "whatever you think," not "sounds good," not silence)
At the stop point, the agent could predict reactions to the next three questions it would ask
Any handoff to a downstream skill (idea-refine, spec-driven-development) was framed in terms of the confirmed intent, not the original underspecified ask

idea-refine

name: idea-refine description: Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan".

Idea Refine

Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking.

How It Works

Understand & Expand (Divergent): Restate the idea, ask sharpening questions, and generate variations.
Evaluate & Converge: Cluster ideas, stress-test them, and surface hidden assumptions.
Sharpen & Ship: Produce a concrete markdown one-pager moving work forward.

Usage

This skill is primarily an interactive dialogue. Invoke it with an idea, and the agent will guide you through the process.

# Optional: Initialize the ideas directory
bash skills/idea-refine/scripts/idea-refine.sh

Trigger Phrases:

"Help me refine this idea"
"Ideate on [concept]"
"Stress-test my plan"

Output

The final output is a markdown one-pager saved to docs/ideas/[idea-name].md (after user confirmation), containing:

Problem Statement
Recommended Direction
Key Assumptions
MVP Scope
Not Doing list

Detailed Instructions

You are an ideation partner. Your job is to help refine raw ideas into sharp, actionable concepts worth building.

Philosophy

Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.
Start with the user experience, work backwards to technology.
Say no to 1,000 things. Focus beats breadth.
Challenge every assumption. "How it's usually done" is not a reason.
Show people the future — don't just give them better horses.
The parts you can't see should be as beautiful as the parts you can.

Process

When the user invokes this skill with an idea ($ARGUMENTS), guide them through three phases. Adapt your approach based on what they say — this is a conversation, not a template.

Phase 1: Understand & Expand (Divergent)

Goal: Take the raw idea and open it up.

Restate the idea as a crisp "How Might We" problem statement. This forces clarity on what's actually being solved.
Ask 3-5 sharpening questions — no more. Focus on:
- Who is this for, specifically?
- What does success look like?
- What are the real constraints (time, tech, resources)?
- What's been tried before?
- Why now?
Use the AskUserQuestion tool to gather this input. Do NOT proceed until you understand who this is for and what success looks like.
Generate 5-8 idea variations using these lenses:
- Inversion: "What if we did the opposite?"
- Constraint removal: "What if budget/time/tech weren't factors?"
- Audience shift: "What if this were for [different user]?"
- Combination: "What if we merged this with [adjacent idea]?"
- Simplification: "What's the version that's 10x simpler?"
- 10x version: "What would this look like at massive scale?"
- Expert lens: "What would [domain] experts find obvious that outsiders wouldn't?"
Push beyond what the user initially asked for. Create products people don't know they need yet.

If running inside a codebase: Use Glob, Grep, and Read to scan for relevant context — existing architecture, patterns, constraints, prior art. Ground your variations in what actually exists. Reference specific files and patterns when relevant.

Read frameworks.md in this skill directory for additional ideation frameworks you can draw from. Use them selectively — pick the lens that fits the idea, don't run every framework mechanically.

Phase 2: Evaluate & Converge

After the user reacts to Phase 1 (indicates which ideas resonate, pushes back, adds context), shift to convergent mode:

Cluster the ideas that resonated into 2-3 distinct directions. Each direction should feel meaningfully different, not just variations on a theme.
Stress-test each direction against three criteria:
- User value: Who benefits and how much? Is this a painkiller or a vitamin?
- Feasibility: What's the technical and resource cost? What's the hardest part?
- Differentiation: What makes this genuinely different? Would someone switch from their current solution?
Read refinement-criteria.md in this skill directory for the full evaluation rubric.
Surface hidden assumptions. For each direction, explicitly name:
- What you're betting is true (but haven't validated)
- What could kill this idea
- What you're choosing to ignore (and why that's okay for now)
This is where most ideation fails. Don't skip it.

Be honest, not supportive. If an idea is weak, say so with kindness. A good ideation partner is not a yes-machine. Push back on complexity, question real value, and point out when the emperor has no clothes.

Phase 3: Sharpen & Ship

Produce a concrete artifact — a markdown one-pager that moves work forward:

# [Idea Name]

## Problem Statement
[One-sentence "How Might We" framing]

## Recommended Direction
[The chosen direction and why — 2-3 paragraphs max]

## Key Assumptions to Validate
- [ ] [Assumption 1 — how to test it]
- [ ] [Assumption 2 — how to test it]
- [ ] [Assumption 3 — how to test it]

## MVP Scope
[The minimum version that tests the core assumption. What's in, what's out.]

## Not Doing (and Why)
- [Thing 1] — [reason]
- [Thing 2] — [reason]
- [Thing 3] — [reason]

## Open Questions
- [Question that needs answering before building]

The "Not Doing" list is arguably the most valuable part. Focus is about saying no to good ideas. Make the trade-offs explicit.

Ask the user if they'd like to save this to docs/ideas/[idea-name].md (or a location of their choosing). Only save if they confirm.

Anti-patterns to Avoid

Don't generate 20+ ideas. Quality over quantity. 5-8 well-considered variations beat 20 shallow ones.
Don't be a yes-machine. Push back on weak ideas with specificity and kindness.
Don't skip "who is this for." Every good idea starts with a person and their problem.
Don't produce a plan without surfacing assumptions. Untested assumptions are the #1 killer of good ideas.
Don't over-engineer the process. Three phases, each doing one thing well. Resist adding steps.
Don't just list ideas — tell a story. Each variation should have a reason it exists, not just be a bullet point.
Don't ignore the codebase. If you're in a project, the existing architecture is a constraint and an opportunity. Use it.

Tone

Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a facilitator reading from a script. Channel the energy of "that's interesting, but what if..." -- always pushing one step further without being exhausting.

Read examples.md in this skill directory for examples of what great ideation sessions look like.

Red Flags

Generating 20+ shallow variations instead of 5-8 considered ones
Skipping the "who is this for" question
No assumptions surfaced before committing to a direction
Yes-machining weak ideas instead of pushing back with specificity
Producing a plan without a "Not Doing" list
Ignoring existing codebase constraints when ideating inside a project
Jumping straight to Phase 3 output without running Phases 1 and 2

Verification

After completing an ideation session:

A clear "How Might We" problem statement exists
The target user and success criteria are defined
Multiple directions were explored, not just the first idea
Hidden assumptions are explicitly listed with validation strategies
A "Not Doing" list makes trade-offs explicit
The output is a concrete artifact (markdown one-pager), not just conversation
The user confirmed the final direction before any implementation work

spec-driven-development

name: spec-driven-development description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.

Spec-Driven Development

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to Use

Starting a new project or feature
Requirements are ambiguous or incomplete
The change touches multiple files or modules
You're about to make an architectural decision
The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

The Gated Workflow

Spec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Phase 0: Scope Check

Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.

Detection. Decompose before specifying when a single requirement bundles several independently testable capabilities:

The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting)
Acceptance criteria cluster into groups that could ship and be verified separately
One capability could be cut or replaced without rewriting the others' requirements

Propose a capability map before writing any spec. Small and reviewable — a module table plus a build order, not a project plan:

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting

Stable module ids. Kebab-case, chosen once, never renamed mid-initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active.
Dependency direction, no cycles. Arrows point one way. If two modules each need the other, they are one module.
Interfaces live at the boundary. The map records that billing depends on identity; the contract between them belongs in the provider module's spec (see api-and-interface-design for designing it).

The map is gated like every phase. The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not.

Then recurse per module. Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map at the project root and each module's spec alongside it, named by module id (SPEC-identity.md, SPEC-billing.md) — the map, not filename guessing, is the index of what exists.

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.

Surface assumptions immediately. Before writing any spec content, list what you're assuming:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.

Write a spec document covering these six core areas:

Objective — What are we building and why? Who is the user? What does success look like?

Commands — Full executable commands with flags, not just tool names.

Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev

Project Structure — Where source code lives, where tests go, where docs belong.

src/           → Application source code
src/components → React components
src/lib        → Shared utilities
tests/         → Unit and integration tests
e2e/           → End-to-end tests
docs/          → Documentation

Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.
Boundaries — Three-tier system:
- Always do: Run tests before commits, follow naming conventions, validate inputs
- Ask first: Database schema changes, adding dependencies, changing CI config
- Never do: Commit secrets, edit vendor directories, remove failing tests without approval

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Phase 2: Plan

With the validated spec, generate a technical implementation plan:

Identify the major components and their dependencies
Determine the implementation order (what must be built first)
Note risks and mitigation strategies
Identify what can be built in parallel vs. what must be sequential
Define verification checkpoints between phases

Follow planning-and-task-breakdown for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, planning-and-task-breakdown takes precedence.

Output convention: Save the plan to tasks/plan.md and record the task list in the task list target defined by planning-and-task-breakdown (default tasks/todo.md; projects may designate an external tracker instead). Create tasks/ if it does not exist. Downstream commands (/build, etc.) expect these defaults.

The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."

Phase 3: Tasks

Break the plan into discrete, implementable tasks:

Each task should be completable in a single focused session
Each task has explicit acceptance criteria
Each task includes a verification step (test, build, manual check)
Tasks are ordered by dependency, not by perceived importance
No task should require changing more than ~5 files

Follow planning-and-task-breakdown for the full task-sizing and dependency-ordering mechanics; it is the canonical source. The template below is a lightweight inline form; if they ever diverge, planning-and-task-breakdown takes precedence.

Task template:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

Phase 4: Implement

Execute tasks one at a time following skills/incremental-implementation/SKILL.md (incremental-implementation) and skills/test-driven-development/SKILL.md (test-driven-development). Use skills/context-engineering/SKILL.md (context-engineering) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.

Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
Update when scope changes — Features added or cut should be reflected in the spec.
Commit the spec — The spec belongs in version control alongside the code.
Reference the spec in PRs — Link back to the spec section that each PR implements.

Common Rationalizations

Rationalization	Reality
"This is simple, I don't need a spec"	Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it"	That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down"	A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway"	That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want"	Even clear requests have implicit assumptions. The spec surfaces those assumptions.
"It's one big feature; splitting it is overhead"	If acceptance criteria cluster into independently testable groups, a monolithic spec forces every downstream task to reason over the whole contract. A ten-line capability map is the cheap alternative.
"I'll decompose during planning"	Planning slices tasks within a spec. By then the oversized artifact already exists — module boundaries and dependency direction must be decided before the spec is written, not after.

Red Flags

Starting to write code without any written requirements
Asking "should I just start building?" before clarifying what "done" means
Implementing features not mentioned in any spec or task list
Making architectural decisions without documenting them
Skipping the spec because "it's obvious what to build"
One spec whose requirements span several independently testable capabilities
Module boundaries or build order decided implicitly during implementation because no capability map was approved up front

Verification

Before proceeding to implementation, confirm:

The spec covers all six core areas
The human has reviewed and approved the spec
Success criteria are specific and testable
Boundaries (Always/Ask First/Never) are defined
The spec is saved to a file in the repository
If the request bundles several independently testable capabilities, a capability map (module ids, dependency direction, build order) was approved before any module spec was written
Every module spec traces to a module id in the approved map

constraint-driven-development

name: constraint-driven-development description: Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read.

Constraint-Driven Development

Overview

Other skills in this pack describe what good looks like. code-review-and-quality gives you five axes. test-driven-development gives you a cycle. security-and-hardening gives you a threat list. All of that lives in prose the agent reads and may or may not follow, and none of it survives the end of the session.

This skill produces something different: a written record of this project's bar, with numbers, that outlives the conversation and can be checked mechanically.

The reason matters. When you wrote the code, reading it told you whether it was any good. An agent writes more in an afternoon than you will read that week, so the judgement moves out of your head and into checks that run around the loop. Those checks need to exist, they need numbers you actually chose, and they need to fire close enough to the work that the agent fixes its own output.

Spec-driven development says what to build. Test-driven development proves it works. Constraint-driven development defines what "good enough to ship" means, before anyone argues about it in a pull request.

When to Use

Apply this skill when:

Starting a project or a significant feature and no quality bar is written down
The user asks to "set up constraints", "add quality gates", "define our standards", or "stop the agent shipping junk"
An agent is producing volume nobody is reading line by line
CI has checks but nobody can say which ones block a merge and which ones are decoration
Coverage, performance, or accessibility numbers get argued about per-PR instead of decided once
You're about to run /build auto or any autonomous loop, and the only thing standing between it and main is a test suite the agent also wrote

When NOT to use:

The project already has a CONSTRAINTS.md and the user isn't changing it — read it and follow it instead
One-off scripts, spikes, throwaway prototypes
The user wants a code review right now (code-review-and-quality) or a CI pipeline built (ci-cd-and-automation)
Pre-product-market-fit code with a two-week expected lifetime — the floor below is still worth it, the rest isn't

Loading Constraints

The interview needs a live user. Don't run it in non-interactive contexts (CI, /loop, autonomous runs). If constraints are missing and you're in one of those, apply the Floor below, note that you did, and flag the rest for a human.

The Process

Step 1: Detect before you ask

Never ask what you can read. Before the first question, gather:

What	Where to look
Language and stack	`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
Test runner	dev dependencies, `test` script, existing test files
Existing linters	`eslint.config.*`, `biome.json`, `.ruff.toml`
Coverage today	`coverage/` output, or run the suite once
CI	`.github/workflows/`, `.gitlab-ci.yml`
Agent harness	`.claude/`, `.codex/`, `AGENTS.md`

Report what you found in two lines, then ask only what's left.

Step 2: Four questions, each with a default

Follow the one-question-at-a-time discipline from interview-me, with one change: every question here has a default, so "I don't know" is a complete answer that still produces a working config.

Q1: Beyond the floor, which of these do you want enforced?
    (a) Test coverage on new code
    (b) Security scanning
    (c) Performance budgets
    (d) Accessibility
    (e) Architecture boundaries
GUESS: (a) and (b) — you have a test runner already and you're handling user input.
DEFAULT if unsure: (a) and (b).
Say what each pick costs: (c) and (d) need a running URL, (e) needs a rules file written.

Q2: When a check fails while the agent is mid-task, should it block or warn?
GUESS: Block. You're running agents unattended and a warning nobody reads is a warning.
DEFAULT if unsure: Block on the floor, warn on everything else for the first two weeks.

Q3: Do you have target numbers in mind, or should I measure where you are today and hold that line?
GUESS: Measure. Most teams don't have a number, and an invented one gets ignored.
DEFAULT if unsure: Measure and hold. See "Ratchets" below.

Q4: What's the slowest check you'll tolerate before the agent hands work back?
GUESS: About 90 seconds. Longer and you'll stop running it.
DEFAULT if unsure: 90 seconds at task end, unlimited in CI.

Stop at four. A twelve-question intake produces a config nobody understands and a user who regrets starting.

Step 3: Write CONSTRAINTS.md

One file at the repo root. Any agent on any harness can read it, and a change to it shows up in review where it belongs.

# Constraints

Last reviewed: 2026-08-08 by @addy

## Floor (always enforced, no setup required)

- No new suppression comments: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
- No unimplemented stubs: `throw new Error("Not implemented")`, empty `catch {}`
- No skipped or deleted tests without a reason in the commit message
- No secrets in source
- This file does not get weakened to make a change pass

## Enforced with numbers

| Dimension | Rule | Checked by | Runs at |
|-----------|------|-----------|---------|
| Types | Zero type errors | `tsc --noEmit` | every edit |
| Lint | Zero errors from our config | `biome check` | every edit |
| Secrets | No secrets in source | `gitleaks detect --redact` | every edit |
| Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI |
| Security: code | No high findings | `semgrep scan --config p/default` | CI |
| Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI |
| Accessibility | Zero critical or serious | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | preview deploy |
| Performance | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | preview deploy |

Every row names the command that produces the verdict. A dimension with a
number and no command in this column is an aspiration, not a constraint.

## Measured, not yet enforced

| Metric | Today | Direction |
|--------|-------|-----------|
| Project coverage | 62.4% | must not fall |
| Bundle size (main) | 184 kB | must not grow |

## Exceptions

| ID | Rule | Path | Reason | Owner | Expires |
|----|------|------|--------|-------|---------|
| W1 | `no-explicit-any` | `src/legacy/**` | Rewrite tracked in ENG-441 | @addy | 2026-11-01 |

Then add one line to AGENTS.md and CLAUDE.md: Read CONSTRAINTS.md before writing code. Do not weaken it to make a change pass.

Step 4: Install what each dimension needs

Picking a dimension means installing something. Don't leave the user with a number and no mechanism, and don't invent your own checker when a de facto one exists — these tools are listed because their rule formats and thresholds are what everything else in the ecosystem targets, so the team's existing config keeps working.

Dimension	Tool	Install	Run	Gate on
Types (TS)	tsc	already there	`tsc --noEmit`	any error
Types (Python)	mypy	`pip install mypy`	`mypy .`	any error
Lint	your existing config	already there	`eslint .` / `biome check` / `ruff check`	any error
Coverage (JS)	your test runner	already there	`vitest run --coverage` (or `jest --coverage`)	coverage of changed lines
Coverage (Python)	pytest-cov	`pip install pytest-cov`	`pytest --cov --cov-report=lcov`	same
Security: code	Semgrep	`pipx install semgrep`	`semgrep scan --config p/default --config p/owasp-top-ten`	any high finding
Security: secrets	gitleaks	`brew install gitleaks`	`gitleaks detect --redact --no-banner`	any finding
Security: dependencies	osv-scanner	`brew install osv-scanner`	`osv-scanner scan source -r .`	high or above
Performance: page	Lighthouse	`npm i -D lighthouse`	`lighthouse $URL --output=json --quiet`	LCP, CLS, performance score
Performance: bundle	size-limit	`npm i -D size-limit`	`size-limit --json`	per-entry byte budget
Accessibility	axe-core	`npm i -D @axe-core/cli`	`axe $URL --tags wcag2a,wcag2aa,wcag21aa`	zero critical or serious
Architecture	dependency-cruiser	`npm i -D dependency-cruiser`	`depcruise --validate src`	any violation
Assertion quality	Stryker	`npm i -D @stryker-mutator/core`	`stryker run --mutate <changed files>`	mutation score

Five things that will bite you if you skip them:

--redact on gitleaks is not optional. Without it the matched secret lands in the agent's transcript, which is how a leaked key ends up in a log, a summary, or a commit message. Report the rule and the location, never the value.
Lighthouse and axe need a URL. They only work against a running app, so they belong in the runtime stage against a preview deploy or a local server you start first. If the project has no URL to hit — a CLI, a library, a desktop app — say so and drop the dimension rather than inventing a check that can't run.
Scope the expensive ones to the diff. stryker run --mutate on the whole repo takes hours and gets turned off; on the files a change touched it takes under a minute. Same for Semgrep, which takes a path list.
Coverage needs no second test run. Read the lcov your suite already writes and intersect it with git diff. Running the suite twice to get a number is the fastest way to make people hate this.
Semgrep's registry rules are free to run; check the licence before redistributing them. opengrep is a drop-in fork with the same rule format and JSON output if that matters to your legal team.

Add each one to the project's own script so it's reproducible without an agent:

{
  "scripts": {
    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
    "check:task": "npm run check:fast && vitest run --coverage",
    "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
  }
}

That mapping matters more than the tools. check:fast is what runs after an edit, check:task when the agent thinks it's done, check:full in CI.

The commands now live in two places — the Checked by column in CONSTRAINTS.md and these scripts. CONSTRAINTS.md is the canonical source: it carries the reason alongside each command and it shows up in review. The scripts are convenience wrappers that must mirror it, not a second source of truth; if they drift, the file wins.

Step 5: Wire it to the lifecycle

The single biggest mistake is running everything everywhere. A check that stalls the agent gets switched off, and a gate people switched off is worse than no gate, because the bar still looks like it exists.

…

Agent Skills

Skill Details

Agent Skills

Commands

Quick Start

Adoption

All 24 Skills

Meta - Discover which skill applies

Define - Clarify what to build

Plan - Break it down

Build - Write the code

Verify - Prove it works

Review - Quality gates before merge

Ship - Deploy with confidence

Agent Personas

Reference Checklists

How Skills Work

Project Structure

Why Agent Skills?

How it compares

Contributing

Team

using-agent-skills

name: using-agent-skills description: Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.

Using Agent Skills

Overview

Skill Discovery

Core Operating Behaviors

1. Surface Assumptions

2. Manage Confusion Actively

3. Push Back When Warranted

4. Enforce Simplicity

5. Maintain Scope Discipline

6. Verify, Don't Assume

Failure Modes to Avoid

Skill Rules

Lifecycle Sequence

Quick Reference

interview-me

Interview Me

Overview

When to Use

Loading Constraints

The Process

Step 1: Hypothesize, with a confidence number

Step 2: Ask one question at a time, each with a guess attached

Step 3: Listen for "want vs. should want"

Step 4: Restate intent in the user's own words

Step 5: Confirm — explicit yes, not "whatever you think"

The 95% Confidence Stop

Output

Example

Interaction with Other Skills

Common Rationalizations

Red Flags

Verification

idea-refine

Idea Refine

How It Works

Usage

Output

Detailed Instructions

Philosophy

Process

Phase 1: Understand & Expand (Divergent)

Phase 2: Evaluate & Converge

Phase 3: Sharpen & Ship

Anti-patterns to Avoid

Tone

Red Flags

Verification

spec-driven-development

Spec-Driven Development

Overview

When to Use

The Gated Workflow

Phase 0: Scope Check

Phase 1: Specify

Phase 2: Plan

Phase 3: Tasks