Skip to content
/
Tier B A19 Token-efficient encoding

claude-code-bmad-skills

claude-code-bmad-skills · aj-geddes/claude-code-bmad-skills · ★ 435 · last commit 2026-03-02

Token-efficient re-implementation of BMAD-METHOD using Claude Code's native skill-md format with 3 lifecycle hooks and a project-level taxonomy for workflow routing.

Best whenBMAD persona files are token-wasteful; functional skill descriptions with decision tables produce equivalent behavior at 70-85% lower token cost.
Skip ifLoading full persona YAML on every agent invocation, Implementing without defining API contract first
vs seeds
superpowers(skill-md format, lifecycle hooks). Uses Claude Code native skill-md format instead of BMAD's persona-md, replaces YAML …
Primitive shape 14 total
Commands 2 Skills 9 Hooks 3
00

Summary

claude-code-bmad-skills — Summary

claude-code-bmad-skills is a token-optimized re-implementation of the BMAD-METHOD for Claude Code's native skills infrastructure. Created by aj-geddes, it ships 9 skills (bmad-orchestrator, business-analyst, product-manager, system-architect, scrum-master, developer, ux-designer, builder, creative-intelligence) installed via a shell/PowerShell installer to ~/.claude/skills/bmad/. Unlike upstream BMAD-METHOD which uses YAML-in-markdown persona files and relies on copy-paste activation, this port uses Claude Code's skill-md format (SKILL.md files with frontmatter) and 3 Claude Code lifecycle hooks (SessionStart, PreToolUse, PostToolUse). The README claims 70-85% token reduction via a "helper pattern" and explicitly removes persona/character overhead in favor of functional skill design. 435 stars, 75 forks, 3 contributors, last pushed March 2026.

differs_from_seeds: Most similar to bmad-method (seed) for the workflow pattern (same 4-phase BMAD agile loop, same agent role names), but the implementation format matches superpowers (skill-md files, Claude Code lifecycle hooks). Key delta from the seed: replaces BMAD's persona-md format with Claude Code's skill-md format, drops character/persona overhead, adds SessionStart/PreToolUse/PostToolUse hooks for environment detection, and adds a bash-script installer vs the seed's npx bmad-method install. The /workflow-init and /workflow-status commands (claude-code slash commands) are a surface not present in either upstream BMAD or superpowers.

01

Overview

claude-code-bmad-skills — Overview

Origin

Created by aj-geddes (GitHub: aj-geddes/claude-code-bmad-skills). Licensed under NOASSERTION (custom/unclear). 435 stars, 75 forks, 3 contributors. Available on Smithery: smithery.ai/skills?ns=aj-geddes.

The README prominently attributes the methodology:

"The BMAD Method (Breakthrough Method for Agile AI-Driven Development) is created and maintained by the BMAD Code Organization. All credit for the BMAD methodology belongs to BMAD Code Organization." "This repository is an implementation of the BMAD Method specifically adapted for Claude Code's native features (Skills, Commands, Hooks, Memory, Files)."

What It Changes from Upstream BMAD

The repo lists four explicit adaptations:

  1. Token efficiency — "70-85% optimization via helper pattern"
  2. Claude Code native integration — no external dependencies
  3. Cross-platform support — Windows (PowerShell), Linux, macOS, WSL
  4. Functional design — "removed persona overhead for better performance"

The "helper pattern" is the key innovation: instead of loading a full 200-line persona YAML file per agent, skills load only the relevant task definition at invocation time.

Project Levels

The orchestrator skill introduces a "project level" taxonomy:

  • Level 0: Single atomic change (1 story) — quick fixes
  • Level 1: Small feature (1-10 stories) — single feature additions
  • Level 2: Medium feature set (5-15 stories) — multiple related features
  • Level 3: Complex integration (12-40 stories) — system integrations
  • Level 4: Enterprise expansion (40+ stories) — large-scale projects

Planning requirements scale with project level:

  • Level 0-1: Tech Spec required, PRD optional
  • Level 2+: PRD required, Architecture required

Documentation Site

A documentation site exists at https://aj-geddes.github.io/claude-code-bmad-skills with examples.

02

Architecture

claude-code-bmad-skills — Architecture

Distribution

  • Type: skill-pack (Claude Code native skills)
  • Install: ./install-v6.sh (Linux/macOS/WSL) or .\install-v6.ps1 (Windows)
  • Runtime: bash (install only; skills themselves are markdown)
  • License: NOASSERTION (unclear — custom license)

Directory Structure

claude-code-bmad-skills/
├── bmad-skills/                   # Primary install path → ~/.claude/skills/bmad-skills/
│   ├── bmad-orchestrator/
│   │   ├── SKILL.md               # Claude Code skill definition
│   │   ├── resources/
│   │   ├── scripts/
│   │   └── templates/
│   ├── business-analyst/
│   │   └── SKILL.md
│   ├── product-manager/
│   │   └── SKILL.md
│   ├── system-architect/
│   │   └── SKILL.md
│   ├── scrum-master/
│   │   └── SKILL.md
│   ├── developer/
│   │   └── SKILL.md
│   ├── ux-designer/
│   │   └── SKILL.md
│   ├── builder/
│   │   └── SKILL.md
│   ├── creative-intelligence/
│   │   └── SKILL.md
│   ├── shared/                    # Helper files (token-saving)
│   ├── hooks/
│   │   ├── bmad-session-start.sh  # SessionStart hook
│   │   ├── bmad-pre-tool.sh       # PreToolUse hook
│   │   └── bmad-post-tool.sh      # PostToolUse hook
│   ├── examples/
│   └── settings.json              # Reference settings for hook configuration
├── bmad-v6/                       # v6 work-in-progress
│   ├── commands/                  # Slash commands
│   ├── config/
│   ├── skills/
│   │   ├── core/
│   │   ├── bmb/                   # BMAD Module B
│   │   ├── bmm/                   # BMAD Module M
│   │   └── cis/                   # Creative Intelligence Suite
│   ├── templates/
│   └── utils/
├── install-v6.sh                  # Linux/macOS installer
├── install-v6.ps1                 # Windows installer
└── CLAUDE.md                      # Project config

Hook Events

Script Event Purpose
bmad-session-start.sh SessionStart Detects BMAD project (reads bmad/config.yaml), sets env vars
bmad-pre-tool.sh PreToolUse Pre-tool checks
bmad-post-tool.sh PostToolUse Post-tool validation

SessionStart Hook Detail

# Check if in a BMAD project
if [ -f "bmad/config.yaml" ]; then
    echo 'export BMAD_PROJECT=true' >> "$CLAUDE_ENV_FILE"
    # Extract project name, level, output folder from config
fi

The hook auto-detects BMAD projects by looking for bmad/config.yaml, then injects environment variables into Claude Code's session.

Target AI Tools

Claude Code (primary). Cross-platform: Windows/Linux/macOS/WSL.

03

Components

claude-code-bmad-skills — Components

Skills (9 — in bmad-skills/)

Skill Description
bmad-orchestrator Core orchestrator; manages workflow phases, init/status; triggers /workflow-init, /workflow-status
business-analyst Phase 1 — product discovery and analysis
product-manager Phase 2 — requirements and planning (PRD)
system-architect Phase 3 — system architecture design
scrum-master Phase 4 — sprint planning
developer Phase 4 — story implementation
ux-designer UX design
builder Custom agent and workflow creation
creative-intelligence Brainstorming and research

Claude Code Slash Commands (in bmad-v6/commands/)

Command Purpose
/workflow-init Initialize BMAD directory structure in project
/workflow-status Check progress, get next-step recommendations

Hooks (3 — in bmad-skills/hooks/)

Hook Event
bmad-session-start.sh SessionStart
bmad-pre-tool.sh PreToolUse
bmad-post-tool.sh PostToolUse

Reference Settings (settings.json)

Provides the hooks configuration block to copy into ~/.claude/settings.json.

Shared Directory

bmad-skills/shared/ contains helper files that multiple skills reference — the "helper pattern" for token optimization.

State Files Created by Orchestrator

When /workflow-init runs:

bmad/
├── config.yaml               # Project name, type, level
└── agent-overrides/          # Custom agent configurations

docs/
├── bmm-workflow-status.yaml  # Phase completion tracking
└── stories/                  # Generated stories

.claude/commands/bmad/        # Claude Code commands
05

Prompts

claude-code-bmad-skills — Prompts

Excerpt 1 — bmad-orchestrator SKILL.md Frontmatter + State Detection

From bmad-skills/bmad-orchestrator/SKILL.md:

---
name: bmad-orchestrator
description: Orchestrates BMAD workflows for structured AI-driven development. Use when initializing BMAD in projects, checking workflow status, or routing between 4 phases (Analysis, Planning, Solutioning, Implementation). Manages project configs, tracks progress through project levels 0-4, and coordinates with specialized workflows. Trigger on /workflow-init, /workflow-status, or when users need BMAD setup.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
---

# BMAD Orchestrator

## When to Use This Skill

Use this skill when:
- User requests `/workflow-init` or `/init` - Initialize BMAD in a project
- User requests `/workflow-status` or `/status` - Check progress and get recommendations
- User mentions "BMAD setup" or "start BMAD workflow"
- Project needs structured development methodology
- Coordination between multiple development phases is required

Prompting technique: Claude Code native skill-md format with YAML frontmatter — description field drives auto-activation (Claude Code reads this to decide when to invoke the skill), allowed-tools restricts which tools the skill can use. This is the "functional" approach vs BMAD's persona approach: no character name, no persona style, just task definition.

Excerpt 2 — Orchestrator Phase Decision Logic

From the orchestrator SKILL.md body:

## BMAD Method Overview

### 4 Development Phases

1. **Analysis** (Optional) - Research, brainstorming, product brief
2. **Planning** (Required) - PRD or Tech Spec based on project complexity
3. **Solutioning** (Conditional) - Architecture design for medium+ projects
4. **Implementation** (Required) - Sprint planning, stories, development

### Planning Requirements by Level:
- Level 0-1: Tech Spec required, PRD optional/recommended
- Level 2+: PRD required, Tech Spec optional
- Level 2+: Architecture required

Prompting technique: Decision table embedded in skill body — the model uses the table to determine what to generate rather than reasoning from first principles. This is the "helper pattern" — explicit lookup tables instead of implicit reasoning.

Excerpt 3 — SessionStart Hook (Environment Detection)

From bmad-skills/hooks/bmad-session-start.sh:

if [ -f "bmad/config.yaml" ]; then
    echo 'export BMAD_PROJECT=true' >> "$CLAUDE_ENV_FILE"
    PROJECT_NAME=$(grep "project_name:" bmad/config.yaml | cut -d: -f2 | tr -d ' "')
    if [ -n "$PROJECT_NAME" ]; then
        echo "export BMAD_PROJECT_NAME=\"$PROJECT_NAME\"" >> "$CLAUDE_ENV_FILE"
    fi
    PROJECT_LEVEL=$(grep "project_level:" bmad/config.yaml | cut -d: -f2 | tr -d ' ')
    echo "export BMAD_PROJECT_LEVEL=$PROJECT_LEVEL" >> "$CLAUDE_ENV_FILE"

Technique: Hook-injected environment variables that give the orchestrator context before any user prompt — the session starts with BMAD_PROJECT=true, BMAD_PROJECT_NAME, and BMAD_PROJECT_LEVEL pre-loaded, allowing the orchestrator to skip re-reading the config file.

09

Uniqueness

claude-code-bmad-skills — Uniqueness & Positioning

differs_from_seeds

Bridges bmad-method (workflow/phases) and superpowers (skill-md format, lifecycle hooks). From BMAD it takes the 4-phase agile loop and 9 named role-based agents; from superpowers it takes the Claude Code skill-md format and SessionStart/PreToolUse/PostToolUse hooks. The key architectural delta from upstream BMAD-METHOD: replaces 200-line YAML persona files with lean skill-md frontmatter, adds 3 lifecycle hooks for auto-detection and state tracking, and introduces /workflow-init + /workflow-status slash commands for state-machine workflow management — none of which exist in the bmad-method seed. Compared to bmad-at-claude (the other BMAD port in this batch), this removes session-manager/message-queue complexity in favor of a simpler YAML state file.

Key Positioning

  • Token-efficient BMAD for teams hitting Claude Code context limits with the full BMAD persona files.
  • Cross-platform (Windows PowerShell installer) — unique in this batch.
  • The project-level taxonomy (0-4) with automatic planning requirement gates is a useful refinement not present in upstream BMAD.

Observable Failure Modes

  1. License ambiguity: NOASSERTION license is a legal red flag for enterprise adoption.
  2. "Helper pattern" undocumented: The README claims 70-85% token reduction but the actual helper pattern mechanism is not fully documented — users can't verify the claim.
  3. bmad-v6 vs bmad-skills split: The repo has two parallel structures (bmad-skills/ and bmad-v6/) suggesting an in-progress refactor that may leave users confused about which version to use.
  4. 3 contributors, moderate activity: Last push March 2026 — active but small team.
  5. Smithery dependency: The skill marketplace listing adds a dependency on Smithery's infrastructure for discoverability, which may not be stable long-term.
04

Workflow

claude-code-bmad-skills — Workflow

Phases

Phase Skill Artifact Gate
0 — Init bmad-orchestrator bmad/config.yaml, docs/bmm-workflow-status.yaml User runs /workflow-init, answers project questions
1 — Analysis (optional) business-analyst Product discovery notes User confirms analysis before proceeding
2 — Planning product-manager docs/prd.md or docs/tech-spec.md Level determines: Level ≤1 = Tech Spec; Level ≥2 = PRD required
3 — Solutioning (conditional) system-architect docs/architecture.md Required for Level ≥2 projects
4 — Implementation scrum-master + developer docs/stories/*.md, code Stories must be generated before developer invoked

Project Level → Planning Requirements

Level Stories PRD Tech Spec Architecture
0 1 Optional Required Optional
1 1-10 Optional Required Optional
2 5-15 Required Optional Required
3 12-40 Required Optional Required
4 40+ Required Optional Required

Orchestrator /workflow-status Output Format

Current research: [topic]
Phase completed: [last phase]
Next step: [action]

The orchestrator reads docs/bmm-workflow-status.yaml to determine state and suggests the next skill to invoke.

Approval Gates

  1. /workflow-init — collects project name, type, level; creates config.
  2. PRD vs Tech Spec gate — orchestrator advises based on project level.
  3. Architecture gate — required for Level ≥2; orchestrator blocks implementation until complete.
  4. Story generation gate — scrum-master must generate stories before developer skill activates.

Artifacts Table

Artifact Generated by Location
bmad/config.yaml orchestrator project root
docs/bmm-workflow-status.yaml orchestrator docs/
docs/prd.md product-manager docs/
docs/tech-spec.md product-manager docs/
docs/architecture.md system-architect docs/
docs/stories/*.md scrum-master docs/stories/
06

Memory Context

claude-code-bmad-skills — Memory & Context

Project State File

docs/bmm-workflow-status.yaml is the central state artifact. The orchestrator reads it on each /workflow-status call to determine current phase, what's complete, and what's next.

Config as Memory

bmad/config.yaml stores:

  • project_name
  • project_type (web-app, mobile-app, api, game, library, other)
  • project_level (0-4)
  • output_folder (default: docs)

This config persists across sessions, allowing the orchestrator to resume context without re-querying the user.

SessionStart Hook as Memory Injector

The bmad-session-start.sh hook reads bmad/config.yaml at session start and exports project metadata as environment variables. This is a form of compressed memory injection: instead of loading the full config file, the key values arrive as env vars at session start.

Cross-Session Handoff

Yes — bmad/config.yaml + docs/bmm-workflow-status.yaml persist between sessions. The orchestrator can detect current state from these files without human re-briefing.

Token Optimization (Helper Pattern)

The README claims 70-85% token reduction. The mechanism:

  • Skills load only their relevant task definition at invocation (not a full 200-line persona file).
  • bmad-skills/shared/ contains reusable snippets that multiple skills reference via file read rather than inline embedding.
  • No character backstory, no persona history — just functional instructions.

Compaction Handling

The hooks fire on PreToolUse and PostToolUse, allowing state to be updated before and after each tool call. However, no explicit context-compaction handler is present.

07

Orchestration

claude-code-bmad-skills — Orchestration

Multi-Agent Pattern

Yes — 9 skills serving as functional agents, coordinated by the bmad-orchestrator skill.

Pattern: Sequential with state-machine routing. The orchestrator reads docs/bmm-workflow-status.yaml to determine which phase is current and routes to the appropriate skill. No parallel execution.

Subagent definition format: skill-md — each agent is a Claude Code SKILL.md file with frontmatter (name, description, allowed-tools). This is the Claude Code native format, not BMAD's persona-md format.

Spawn mechanism: Claude Code's skill auto-activation (triggered by description match) or explicit /workflow-init and /workflow-status slash commands.

Isolation

None — in-place editing. Skills write to docs/ folder.

Multi-Model

No — single Claude model. No per-role routing.

Execution Mode

interactive-loop — user runs /workflow-init or /workflow-status, orchestrator responds with current state and next action. No autonomous execution.

Hook-Driven State Updates

3 hooks (SessionStart, PreToolUse, PostToolUse) fire at lifecycle events, updating session state. This is more comprehensive than most BMAD ports — the 3-hook coverage gives the framework visibility into every tool call.

Prompt Chaining

Yes: PRD → Architecture → Stories → Code is an explicit artifact chain. The developer skill is blocked until stories exist; stories reference the PRD and architecture.

08

Ui Cli Surface

claude-code-bmad-skills — UI / CLI Surface

CLI Binary

No dedicated binary. Install is via shell script:

  • Linux/macOS/WSL: ./install-v6.sh
  • Windows: .\install-v6.ps1

The install scripts copy files to ~/.claude/skills/bmad-skills/.

Local UI

None — Claude Code terminal only.

Slash Commands

  • /workflow-init — initialize BMAD project structure
  • /workflow-status — check current phase + next steps

These are Claude Code slash commands (markdown files in .claude/commands/), not a CLI.

Available on Smithery

Listed on smithery.ai/skills?ns=aj-geddes — a skill discovery marketplace for Claude Code, indicating some ecosystem integration.

Cross-Platform

Explicitly supports Windows (PowerShell installer), Linux, macOS, WSL — broader platform coverage than most Claude Code skill packs.

Observability

docs/bmm-workflow-status.yaml is a structured YAML file tracking phase completion, readable as a human-friendly audit log.

Cross-Tool Portability

Low — Claude Code–specific. The skill-md format is a Claude Code primitive; it won't work in other AI tools without conversion.

Related frameworks

same archetype · same primary tool · same memory type

Context Mode ★ 16k
A19 Token-efficient encoding

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context…

lean-ctx ★ 2.2k
A19 Token-efficient encoding

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101
A19 Token-efficient encoding

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28
A19 Token-efficient encoding

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

cursor-coding-agent-os (Mugiwara555343) ★ 3
A19 Token-efficient encoding

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

rtk (Real Token Killer) ★ 55k
A19 Token-efficient encoding

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…