Skip to content
AI CraftsmanSUPERPOWERS

Commands Reference

Complete reference for the AI Craftsman Superpowers skills: usage, effort, and examples.

Last updated: Edit on GitHub

Overview

AI Craftsman Superpowers ships 22 skills, invoked with /craftsman:<name> on Claude Code and Codex. On Grok, use /<name> except plan, loop and workflow stay /craftsman:name. Hermes invokes /craftsman plus situation skills.

Fifteen skills start only when you type them. Seven may start when the model’s context matches: debug, challenge, test, team, rag, mlops, agent-design.

Commands became skills in v4

v4.0.0 moved every workflow to skills/<name>/SKILL.md, gaining forked execution, agent binding and live context injection. Your invocations did not change: /craftsman:design still works exactly as before.

Category Skills
Core Methodology design, challenge, spec, debug, plan, workflow, loop, verify, test, refactor, legacy, git, parallel
Scaffolding scaffold
AI/ML Engineering rag, mlops, agent-design
Utilities setup, healthcheck, metrics, ci, team

Effort levels

Each skill declares the effort Claude Code runs it at, in the effort: key of its SKILL.md: Low, Medium, High or Extra high (xhigh). It overrides the session’s effort level for that skill. “Started by: you or model” marks the seven skills the model may start when the context matches; the others start only when you type them.

/craftsman:design - Senior DDD Methodology

Effort: High | Model: Opus

Four mandatory phases before any code is written. Violating phase order is blocked.

/craftsman:design Create a User aggregate with subscription management

Phases:

  1. Understand - Map domain, identify entities, bounded contexts
  2. Challenge - Question assumptions, explore alternatives, find simpler solutions
  3. Recommend - Select approach with explicit trade-offs
  4. Implement - Write code following DDD tactical patterns

/craftsman:challenge - Architecture Review

Effort: High | Model: Opus | Started by: you or model

3-level severity review for code and architecture decisions.

/craftsman:challenge Review the current authentication implementation

Severity levels:

  • BLOCKING - Must fix before proceeding (security, data corruption risk)
  • MUST FIX - Fix before PR merge (architecture violations)
  • IMPROVE - Suggestion for better design (non-blocking)

/craftsman:spec - Specification-First Development

Effort: Medium | Model: Sonnet

BDD/TDD specification before implementation. The Iron Law: no production code without a failing test first.

/craftsman:spec UserRepository should find users by email

Output: Gherkin scenarios → failing test → implementation plan

/craftsman:debug - Systematic ReAct Debugging

Effort: High | Model: Opus | Started by: you or model

6-phase systematic investigation. No guessing allowed.

/craftsman:debug The user authentication fails intermittently in production

Phases: Observe → Hypothesize → Experiment → Analyze → Root Cause → Fix

/craftsman:plan - Structured Planning

Effort: Extra high | Model: Opus

Three modes for different planning needs:

/craftsman:plan create "Migrate authentication to JWT"  # Create plan
/craftsman:plan execute                                  # Execute current plan
/craftsman:plan execute-with-agents                      # Execute with agent team

Produces a structured markdown plan with phases, dependencies, and success criteria.

/craftsman:scaffold - Unified Code Scaffolder

Effort: Medium | Model: Sonnet

Generates code from canonical examples (Iron Law pattern). Supports multiple scaffold types:

/craftsman:scaffold entity      # DDD Entity with Value Objects + Domain Events
/craftsman:scaffold usecase     # Use Case with Command/Handler (CQRS)
/craftsman:scaffold component   # React component with TypeScript + tests
/craftsman:scaffold hook        # React hook with TanStack Query
/craftsman:scaffold api-resource # API Platform 4 Resource
/craftsman:scaffold pack        # A new pack: manifest, validators, tests

Each scaffold loads the canonical example first, then adapts it to your context.

/craftsman:refactor - Systematic Refactoring

Effort: High | Model: Opus

Safe refactoring with behavior preservation. Detects and addresses code smells.

/craftsman:refactor The UserService class has grown to 800 lines

Code smell catalog: Long method, large class, feature envy, primitive obsession, shotgun surgery, data clumps, parallel inheritance hierarchies.

/craftsman:test - Pragmatic Testing

Effort: Medium | Model: Sonnet | Started by: you or model

Testing pyramid: 80% unit, 15% integration, 5% E2E. Focuses on behavior, not implementation.

/craftsman:test Write tests for the OrderService use case

Rules:

  • AAA structure (Arrange, Act, Assert)
  • One concept per test
  • No testing implementation details
  • Mock only at system boundaries

/craftsman:verify - Evidence-Based Verification

Effort: Low | Model: Haiku

Runs verification before claiming completion. The Golden Rule: no completion claims without fresh verification evidence.

/craftsman:verify

Runs: TypeScript compilation → linting → tests → architecture check. Produces a pass/fail report with evidence.

/craftsman:legacy - Legacy Code Rescue

Effort: Extra high | Model: Opus

Brings untested, tangled, inherited code under control without breaking it. Never rewrites from scratch.

/craftsman:legacy audit      # Rank hotspots by churn x complexity, and say where the first test goes
/craftsman:legacy cover      # Characterization tests around behaviour that exists, bugs included
/craftsman:legacy untangle   # Break a hard dependency with a seam, so the code becomes testable
/craftsman:legacy migrate    # Plan and track a strangler-fig migration

Iron laws:

  1. Never change behaviour while getting code under test. Characterize first, change later.
  2. No big-bang rewrite. Grow the new around the old, retire the old when the new carries the load.
  3. Every step ships green. Small, safe, reversible commits.
  4. The safety net comes before the refactor. No net, no change.

It will not turn your repository red on day one

The structural ratchet measures each file against its own recorded mark, so debt you inherited is not a violation. It becomes one the day someone makes it worse.

/craftsman:loop - Bounded Verification Loop

Effort: High | Model: Opus

The repeat layer over the verify gate, for anything shaped as act, verify, repeat until a stated condition holds: ratchet campaigns, red-to-green test runs, violation burn-down.

/craftsman:loop Extract the three worst offenders in the ratchet baseline

Every iteration re-verifies. The loop stops on green, on no progress, or when the budget is spent, whichever comes first. A bound stated up front is what separates it from an open-ended retry that burns tokens until someone notices.

/craftsman:workflow - Guided Development Pipeline

Effort: Medium | Model: Sonnet

The full cycle, in order, when you want the methodology to hold your hand: design, spec, plan, implement, test, verify, commit.

/craftsman:workflow Add subscription billing to the account context

Each stage hands its output to the next, and the gates run between them rather than at the end.

/craftsman:git - Safe Git Workflow

Effort: Low | Model: Haiku

Conventional Commits enforcement with destructive command protection.

/craftsman:git

Reads the staged and unstaged changes and proposes atomic commits, one concern each, with a conventional commit message for each.

Protected commands (require explicit confirmation): git push --force, git reset --hard, git clean -fd, git branch -D.

/craftsman:metrics - Quality Dashboard

Effort: Low | Model: Haiku

SQLite-backed quality metrics from your sessions.

/craftsman:metrics

Output:

  • Total violations this week / month
  • Corrections made (learning feedback loop)
  • Session history (last 10 sessions)
  • 7-day and 30-day trend charts
  • Top violated rules

/craftsman:ci - CI/CD Integration

Effort: Medium | Model: Sonnet

Generates CI configuration and shows CI status.

/craftsman:ci export    # Generate CI config for your provider
/craftsman:ci status    # Show last CI run status

Detects your provider from .craft-config.yml and generates the appropriate workflow file. See CI Integration for full details.

/craftsman:team - Agent Team Manager

Effort: Extra high | Model: Opus | Started by: you or model

Orchestrates multiple agents for complex tasks. Three built-in templates:

/craftsman:team code-review    # Architect + Security + Doc reviewer in parallel
/craftsman:team feature        # Team-Lead orchestrates Frontend + Backend + Tests
/craftsman:team security-audit # Security specialist deep dive

/craftsman:setup - Interactive Configuration Wizard

Effort: Medium | Model: Sonnet

Runs the DISC mini-assessment, detects your stack, and generates ~/.claude/.craft-config.yml. See Getting Started.

/craftsman:healthcheck - Diagnose the Install

Effort: Low | Model: Haiku

Reports what the plugin actually loaded: active packs, resolved rules, which gate levels are live on this machine, and which language servers were detected.

/craftsman:healthcheck

There is no session-start command. Config, packs and rules load automatically on SessionStart, so healthcheck is for inspecting that result, not for triggering it.

/craftsman:parallel - Multi-Agent Orchestration

Effort: Extra high | Model: Opus

Identifies independent tasks and runs them in parallel with separate agents.

/craftsman:parallel Implement the user registration feature

Produces a dependency matrix, spawns parallel agents for independent tasks, then merges results.

/craftsman:rag - RAG Pipeline Design

Effort: Extra high | Model: Opus | Started by: you or model

Design RAG pipelines: ingestion, retrieval, generation, and evaluation.

/craftsman:rag Design a Q&A system over internal documentation

Covers: source selection, chunking strategy, embedding model choice, retrieval tuning, prompt engineering, hallucination guards.

/craftsman:mlops - ML Production Readiness Audit

Effort: Extra high | Model: Opus | Started by: you or model

Audit ML projects for production readiness: data pipeline, model versioning, monitoring, infrastructure.

/craftsman:mlops Audit the recommendation model for production

Checks: training/serving skew, feature store design, model registry, A/B testing setup, monitoring and alerting.

/craftsman:agent-design - AI Agent Design

Effort: Extra high | Model: Opus | Started by: you or model

Design AI agents using the 3P pattern: Perceive (understand context), Plan (reason over options), Perform (act and observe).

/craftsman:agent-design Design a customer support triage agent

Produces: agent architecture, tool definitions, prompt templates, failure modes and mitigations.