debug-skills

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

┌─────────────────────────────────────────────────────┐
│  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                │
└─────────────────────────────────────────────────────┘

> /brace my-webapp

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)

> /rig

my-webapp/
├── .github/
│   ├── workflows/ci.yml       # PR validation pipeline
│   └── pull_request_template.md
├── .lefthook.yml              # Git hooks (lint, test on commit)
├── .commitlintrc.yml          # Conventional commit enforcement
└── .editorconfig              # Consistent formatting

> /speccy a user authentication system with OAuth2

> /build implement the auth system from specs/auth-spec.md

graph TD
    A["Stage 1: Explore<br/>Understand codebase"] --> B["Stage 2: Question<br/>Clarify ambiguities"]
    B --> C["Stage 3: Architect<br/>Design solution"]
    C --> D["Stage 4: Implement<br/>Write code"]
    D --> E["Stage 5: Review<br/>Check quality"]
    E --> F["Stage 6: Ship<br/>Invoke /ship"]

    style A fill:#3498db,color:#fff
    style B fill:#3498db,color:#fff
    style C fill:#9b59b6,color:#fff
    style D fill:#2ecc71,color:#fff
    style E fill:#e74c3c,color:#fff
    style F fill:#f39c12,color:#fff

> /ship

sequenceDiagram
    participant Dev as Developer
    participant Ship as /ship
    participant GH as GitHub
    participant CI as CI Pipeline

    Dev->>Ship: /ship
    Ship->>Ship: Stage 1: Sync with main
    Ship->>Ship: Stage 2: Analyze, commit, push
    Ship->>GH: Create PR
    Ship->>CI: Stage 3: Monitor checks
    CI-->>Ship: All checks passed ✅
    Ship->>GH: Stage 5: Squash merge
    Ship->>Ship: Sync local main, cleanup branches
    Ship-->>Dev: Ship complete ✅

> /keel

my-webapp/
├── infra/
│   ├── main.tf                  # Provider, backend, module calls
│   ├── variables.tf             # Input variables
│   ├── outputs.tf               # Registry URL, endpoints, connection strings
│   ├── versions.tf              # Required providers
│   ├── bootstrap.sh             # One-time state backend setup
│   ├── sync-outputs.sh          # Sync TF outputs → CI/CD variables
│   ├── environments/
│   │   ├── dev.tfvars
│   │   ├── staging.tfvars
│   │   └── prod.tfvars
│   └── modules/
│       ├── registry/            # Azure Container Registry
│       ├── compute/             # Azure Container Apps
│       ├── database/            # PostgreSQL Flexible Server
│       ├── networking/          # VNet, subnets
│       └── monitoring/          # Log Analytics, App Insights
└── .github/workflows/
    └── infra.yml                # Plan on PR, apply on merge

graph LR
    subgraph "PR Phase"
        A["Push infra/ changes"] --> B["terraform plan"]
        B --> C["Post plan as<br/>PR comment"]
    end

    subgraph "Merge Phase"
        D["Merge to main"] --> E["terraform apply<br/>(dev)"]
        E --> F["Sync outputs to<br/>CI/CD variables"]
    end

    subgraph "Promotion Phase"
        G["Manual dispatch"] --> H["terraform apply<br/>(staging)"]
        H --> I["terraform apply<br/>(prod)"]
    end

    C --> D
    F --> G

    style B fill:#3498db,color:#fff
    style E fill:#2ecc71,color:#fff
    style H fill:#e67e22,color:#fff
    style I fill:#e74c3c,color:#fff

> /dock

my-webapp/
├── Dockerfile                   # Multi-stage: deps → build → test → production
├── .dockerignore
├── docker-compose.yml           # Local dev parity
├── deploy/
│   └── environments.yml         # Per-environment config matrix
└── .github/workflows/
    └── deploy.yml               # Build, push, deploy pipeline

graph TD
    subgraph "Build Phase (on merge to main)"
        A["Checkout code"] --> B["Build image<br/>target: test"]
        B --> C["Run tests<br/>inside container"]
        C --> D["Build image<br/>target: production"]
        D --> E["Push to registry<br/>tag: abc1234 + latest"]
    end

    subgraph "Deploy Dev"
        E --> F["Deploy abc1234<br/>to dev"]
        F --> G["Smoke tests ✅"]
    end

    subgraph "Promote to Staging (on release tag v1.2.3)"
        G -.-> H["Retag abc1234<br/>as v1.2.3"]
        H --> I["Deploy v1.2.3<br/>to staging"]
        I --> J["Integration +<br/>e2e tests ✅"]
    end

    subgraph "Promote to Production"
        J --> K["Deploy v1.2.3<br/>to production"]
        K --> L["Post-deploy<br/>smoke test ✅"]
    end

    style B fill:#3498db,color:#fff
    style D fill:#3498db,color:#fff
    style E fill:#2ecc71,color:#fff
    style H fill:#e67e22,color:#fff
    style I fill:#e67e22,color:#fff
    style K fill:#e74c3c,color:#fff

    linkStyle 6 stroke:#999,stroke-dasharray:5

graph TB
    subgraph "Developer Workflow"
        DEV["Developer"] -->|"/build"| CODE["Code Changes"]
        CODE -->|"/ship"| PR["Pull Request"]
    end

    subgraph "CI Pipeline (/rig)"
        PR --> LINT["Lint + Validate"]
        LINT --> TEST["Unit Tests"]
        TEST --> PASS{"Checks<br/>pass?"}
        PASS -->|Yes| MERGE["Merge to main"]
        PASS -->|No| FIX["/ship auto-fix"]
        FIX --> LINT
    end

    subgraph "Infrastructure Pipeline (/keel)"
        INFRA_PR["Infra PR"] --> PLAN["terraform plan"]
        PLAN --> INFRA_MERGE["Merge"]
        INFRA_MERGE --> APPLY_DEV["Apply to dev"]
        APPLY_DEV --> SYNC["Sync outputs →<br/>CI/CD vars"]
    end

    subgraph "Deployment Pipeline (/dock)"
        MERGE --> BUILD["Build container<br/>image"]
        BUILD --> PUSH["Push to registry<br/>:sha + :latest"]
        PUSH --> DEPLOY_DEV["Deploy to dev"]
        DEPLOY_DEV --> SMOKE["Smoke tests"]

        TAG["Release tag<br/>v1.2.3"] --> RETAG["Retag image<br/>(no rebuild)"]
        RETAG --> DEPLOY_STG["Deploy staging"]
        DEPLOY_STG --> E2E["e2e tests"]
        E2E --> DEPLOY_PROD["Deploy production"]
        DEPLOY_PROD --> FINAL["Post-deploy smoke"]
    end

    SYNC -.->|"Registry URL<br/>Endpoints"| BUILD

    style DEV fill:#4a9eff,color:#fff
    style MERGE fill:#2ecc71,color:#fff
    style BUILD fill:#3498db,color:#fff
    style PUSH fill:#3498db,color:#fff
    style RETAG fill:#e67e22,color:#fff
    style DEPLOY_PROD fill:#e74c3c,color:#fff

claude plugin marketplace add slamb2k/mad-skills

"extraKnownMarketplaces": {
  "slamb2k": {
    "source": { "source": "github", "repo": "slamb2k/mad-skills" }
  }
}

claude plugin install mad-skills@slamb2k

/plugin install mad-skills@slamb2k

npx skills add slamb2k/mad-skills -g -y              # All skills, global
npx skills add slamb2k/mad-skills --skill ship -g -y  # Specific skill

# Remove old command stubs
rm -f ~/.claude/commands/{brace,build,distil,prime,rig,ship,sync,speccy}.md

# Remove installer manifest and stale skill files
rm -f ~/.claude/.mad-skills-manifest.json
rm -f ~/.claude/skills/*/instructions.md

ln -sfn "$DOTFILES_DIR/skills/my-skill" "$HOME/.claude/skills/my-skill"

mad-skills/
├── skills/                  # Skill definitions (10 skills)
│   ├── build/
│   ├── brace/
│   ├── distil/
│   ├── dock/
│   ├── keel/
│   ├── prime/
│   ├── rig/
│   ├── ship/
│   ├── speccy/
│   └── sync/
├── scripts/                 # Build and CI tooling
│   ├── validate-skills.js   # Structural validation
│   ├── lint-skills.js       # SKILL.md linting
│   ├── run-evals.js         # Eval runner (Anthropic/OpenRouter)
│   ├── build-manifests.js   # Generate skills/manifest.json
│   └── package-skills.js    # Package .skill archives
├── hooks/                   # Session hooks + plugin hook config
├── agents/                  # Agent definitions (reserved for future use)
├── tests/results/           # Eval output
├── archive/                 # Legacy skills (v1.x)
├── .claude-plugin/          # Plugin metadata
│   ├── marketplace.json
│   └── plugin.json
└── .github/workflows/
    └── ci.yml               # Unified CI, evals, and release

skills/<name>/
├── SKILL.md              # Frontmatter + banner + execution logic (single file)
├── references/           # Extracted prompts, contracts, guides
├── assets/               # Static files (templates, components)
└── tests/
    └── evals.json        # Eval cases for the skill

# Validate all skill structures
npm run validate

# Lint SKILL.md files
npm run lint

# Run evals (requires ANTHROPIC_API_KEY or OPENROUTER_API_KEY)
npm run eval
npm run eval -- --verbose
npm run eval:update              # Update eval snapshots

# Build
npm run build:manifests          # Generate skills/manifest.json
npm run build:skills             # Package .skill archives
npm run build                    # Both

# Full test suite
npm test                         # validate + lint + eval