The registry and skills

Behind every roster, count and generated instruction file of BMAD+ there is one file: registry.yaml, at the root of the BMAD+ source repository. It declares the packs, their agents, skills, data files, install layout, runtimes and compliance tags, the adapters, the data-handling doctrine and more. Everything downstream is generated from it, so a roster, a number or an adapter cannot drift from the declarations. This page is for people who want to understand that contract, read the generated files with confidence, or extend BMAD+ in a fork or a team distribution.

What the registry declares#

uses_skills: what an agent drives#

A pack or a persona lists the skill ids it drives. The generator resolves each id: it must be a skill of any pack, of an external_module or of Core, and an id nobody ships fails the build. The spine roster then shows - drives: design, design-review, redesign after the persona, and the generated instructions tell the agent to read the SKILL.md of each listed skill before acting on it. Here is the real declaration of the Design pack’s persona.

  design:
    order: 9
    display_name: "Design"
    required: false
    runtime: [node]
    agents: [design-engine]
    personas:
      - { id: design-engine, name: Atelier, role: Design Engine, description: "Senior product designer and design engineer: surfaces, tokens, accessibility, audits, redesigns", uses_skills: [design, design-review, redesign] }
    skills: []
    external_module: { package: design-skill, version: "0.2.1", skills: [design, design-review, redesign] }
    pack_dir: pack-design
    install_layout: packaged
    doctor:
      pack_agents: [design-engine.md]
      required_resources: [SKILL.md]
    intake: intake.yaml
    cohabitation_warning: "Overlaps Sentinel's UX-review role and Dev Studio's Rachel (UX Designer); ..."

external_module: skills from an npm package#

A pack may take its skills from a published package instead of the BMAD+ tree. The Design pack is the first: its three skills come from design-skill, pinned at the exact version 0.2.1. The package is an exact dependency of BMAD+ and is listed in the data-handling doctrine. At build time the generator resolves the package, checks that its version equals the declared one and that skills/<id>/SKILL.md exists for each listed skill. At install time BMAD+ resolves the package from its own install, refuses a version mismatch, and copies only the package’s skills/ directory into .agents/skills/<id>/ through the same managed, hash-inventoried copy as every other file (no symlink is followed). The tarball also ships a linker command-line tool that BMAD+ never runs. bmad-plus doctor requires the three SKILL.md files; uninstall removes the copied skills with the rest of the managed files.

pipelines: ordered steps with a gate#

A pack can declare pipelines: an ordered run of its own workflows or agents, each step with one gate (require_approval, notify_only or auto). Nexus runs a declared pipeline step by step with the configured checkpoint behaviour, after the pack’s intake. Pipeline ids must be unique in the pack and each step names exactly one workflow or one agent that exists in the pack. No pack declares a pipeline in 0.23.0: the field exists, is validated and is understood by autopilot, and is there for packs that need it. The example is the format from the specification, not shipped content.

pipelines:
  - id: full-build
    title: From interview to private preview
    steps:
      - { workflow: discovery, gate: require_approval }
      - { workflow: positioning, gate: require_approval }
      - { agent: brandsite-art, gate: notify_only }
      - { workflow: preview, gate: require_approval }

Triggers that must point at real things#

.agents/data/role-triggers.yaml drives role switching. The check npm run check:triggers (in the source repository) validates it against the registry: a top-level key must be a Core agent short name (strategist, architect-dev, quality, orchestrator) or a pack id; default_role must be one of the key’s auto_triggers; each role has a non-empty list of patterns; contexts and reasoning, when present, are lists of snake_case identifiers; under a pack key, each role id is a persona id or a pipeline id of that pack; and an exact pattern repeated across two roles of the same key is an error. The Core contexts that point at the features of this page are three: swarm_declared and panel_requested (Parallel Supervisor) and pack_pipeline_declared (autopilot).

What is generated, and the checks that keep it honest#

What a skill is#

A skill is a folder with a SKILL.md: a front matter with a name and a description (which says when to use it, in words your assistant can match), then the procedure. Longer material sits in a ref/ folder next to it, templates in templates/. Every agent is also a skill: agent-strategist/SKILL.md is Atlas. The host loads the SKILL.md it needs, which is why the description matters: it is what makes an assistant pick the skill. The six Core skills below ship with every installation.

Other skills come with their packs: dev-studio (the dispatcher of the pack), the design, design-review and redesign skills copied from design-skill, the bmad-osint-investigate and bmad-osint-investigator skills of the OSINT package. The SEO and Design packs also carry a router SKILL.md that reacts when you write /seo or /design in a message; these are request keywords, not slash commands registered by your client.

Adding an agent or a pack with Maker#

Maker is the Agent Creator of the Maker pack. It designs an agent with you in four phases (discovery, design with your validation, generation, validation) and writes a package under _bmad-output/ready-to-integrate/. Its capabilities: CA create an agent, QA quick agent with fewer questions, EA edit an existing agent’s SKILL.md in place (it does not go through that folder), VA validate an agent package (format, manifest, unique capability codes, trigger quality), PA package for integration, TP show the template.

1. 01

   Create and validate the agent

   Ask Maker for CA, answer its discovery questions, validate the design table, then run VA on the result.

2. 02

   Copy it into a clone of the repository

   Place the agent folder under src/bmad-plus/agents/ (a loose agent) or in a pack directory (a packaged pack).

3. 03

   Declare it in registry.yaml

   Add or extend a pack: agents, personas (with uses_skills if it drives skills), skills, install_layout, doctor, and, if needed, intake, pipelines, cohabitation_warning. Add role triggers in role-triggers.yaml under the pack id if you want auto-activation.

4. 04

   Regenerate and check

   Run npm run build, node tools/build/generate-adapters.js --adopt, then npm run build:check, npm run check:counts and npm run check:triggers. Each failure names the field to fix.

5. 05

   Install it in a throwaway project

   Run the installer from your clone with --packs core,<your-pack> and then doctor: it must report no error. The install contract of the repository (npm run test:install-contract) checks the same thing for every pack.

In an installed project, without a clone, you can still put your own skill folders under .agents/skills/. BMAD+ treats files it did not install as yours: bmad-plus doctor reports them as unowned (a warning, not an error), and update and uninstall leave them in place. They are not registered in the roster, so the spine does not mention them; add a line to your own instructions file or to the adapter if you want the assistant to find them.

Maker, create a customer support agent for our team: it triages incoming tickets, drafts replies in our tone and escalates anything about billing to a human. Ask me your discovery questions in one batch, show me the design table (name, roles, capabilities with two-letter codes, triggers, dependencies) and wait for my validation before generating. Then validate the package and tell me what is left to declare in the registry.