mad-skills

MAD Skills

A skill framework for Claude Code. Ships 10 skills covering the full development lifecycle — from project initialization to shipping PRs.

Skills

Skill	Command	Description
build	/build	Context-isolated feature development pipeline. Takes a design/plan and executes explore, question, architect, implement, review, ship inside subagents.
brace	/brace	Initialize projects with a standard scaffold. Creates specs/, tools/, context/ directories, project CLAUDE.md, and branch protection.
distil	/distil	Generate multiple unique web design variations. Creates a Vite + React + TypeScript + Tailwind project with N designs at /1, /2, /3.
dock	/dock	Generate container release pipelines. Builds once, promotes immutable images through dev → staging → prod. Supports Azure Container Apps, AWS Fargate, Cloud Run, Kubernetes, Dokku, Coolify, CapRover.
keel	/keel	Generate IaC pipelines (Terraform, Bicep, Pulumi, CDK) to provision cloud infrastructure. Plans on PR, applies on merge. Provisions what /dock deploys to.
prime	/prime	Load project context before feature work. Supports domain-specific context (security, routing, dashboard, etc.).
rig	/rig	Bootstrap repos with lefthook hooks, commit templates, PR templates, and GitHub Actions workflows. Idempotent.
ship	/ship	Full PR lifecycle — sync with main, create branch, commit, push, create PR, wait for CI, fix issues, squash merge, cleanup.
speccy	/speccy	Interview-driven specification builder. Reviews code/docs, interviews through targeted questions, produces structured specs.
sync	/sync	Sync local repo with origin/main. Stashes changes, pulls, restores stash, cleans up stale branches.

Lifecycle Overview

The 10 skills form a complete development-to-deployment pipeline. Each skill produces artifacts that downstream skills consume.

graph LR
    A["/brace<br/>Project Init"] --> B["/rig<br/>Dev Tooling"]
    B --> C["/speccy<br/>Spec Builder"]
    C --> D["/build<br/>Features"]
    D --> E["/ship<br/>Merge PRs"]
    E --> F["/keel<br/>Infra (IaC)"]
    F --> G["/dock<br/>Deploy"]

    style A fill:#4a9eff,color:#fff
    style B fill:#4a9eff,color:#fff
    style C fill:#9b59b6,color:#fff
    style D fill:#2ecc71,color:#fff
    style E fill:#2ecc71,color:#fff
    style F fill:#e67e22,color:#fff
    style G fill:#e67e22,color:#fff

Phase	Skills	What happens
Setup	/brace → /rig	Initialize project structure, install hooks, templates, CI workflows
Develop	/speccy → /build → /ship	Spec features, implement in isolated subagents, merge via PR lifecycle
Deploy	/keel → /dock	Provision cloud infrastructure, then deploy containers to it

Supporting skills (/sync, /prime, /distil) are used as needed throughout:

• /sync — Pull latest changes before starting work
• /prime — Load domain context before complex features
• /distil — Generate multiple web design variations

---

End-to-End Walkthrough

This walkthrough follows a Node.js app from an empty folder to a deployed container running on cloud infrastructure.

Step 0: Session Guard

When you open Claude Code in any project with the mad-skills plugin installed, the session guard runs automatically. It validates your development environment before you write a single line of code.

┌─────────────────────────────────────────────────────┐
│  Session Guard — automatic on every session start    │
│                                                      │
│  ✅ CLAUDE.md found                                  │
│  ✅ Git repository initialized                       │
│  ✅ On branch: main                                  │
│  ⚠️  CLAUDE.md last modified 5 days ago              │
│  ℹ️  Task list configured: my-project                │
└─────────────────────────────────────────────────────┘

The session guard checks: git status, CLAUDE.md presence and freshness, task list configuration, and branch state. If issues are found, they're surfaced before your first prompt.

---

Step 1: /brace — Initialize the Project

Start in an empty folder. /brace creates the project scaffold.

> /brace my-webapp

What it generates:

my-webapp/
├── CLAUDE.md              # AI-readable project instructions
├── .gitignore             # Ignores credentials, data, temp files
├── specs/                 # Specifications (/speccy → /build)
├── context/               # Domain knowledge and references
└── .tmp/                  # Scratch work (gitignored)

The CLAUDE.md it creates becomes the foundation — every subsequent skill reads it for project context.

---

Step 2: /rig — Set Up Dev Tooling

With the skeleton in place, /rig bootstraps the development infrastructure.