# The registry and skills

> registry.yaml as the single source of truth: pack fields, uses_skills, external_module, pipelines, intake, the guarding checks, what is generated, and how a team adds an agent or a pack with Maker.

Canonical: https://bmad-plus.rochetta.fr/docs/concepts/registry-and-skills/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Concepts](https://bmad-plus.rochetta.fr/docs/concepts/) › 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.

> **Note · A source-level file** The npm package ships the generated results (the pack definitions in the CLI, `module.yaml`, the adapters) and the generator scripts `tools/build/generate.js`, `generate-adapters.js` and `intake-contract.js`, but not `registry.yaml` itself. An installed project therefore never contains the registry; it contains `AGENTS.md`, `_bmad/module.yaml` and the skills. To change the registry you work in a clone of the BMAD+ repository.

<a id="what-it-declares"></a>
## What the registry declares

**Top-level sections of registry.yaml**

| Section | Content |
| --- | --- |
| `product` | Code name, display name, version (checked against `package.json`), the BMAD-METHOD version it derives from, whether the upstream notice must be retained. |
| `targets` | The spine file, the integration contract (`execution: host-managed`, `lifecycle_events: not-integrated`), the optional process backend (`command`, `codex-exec`, foreground supervisor, no scheduling), the seven adapters and the model families supported (`claude`, `gpt`, `gemini`, `local`). |
| `runtimes` | Node.js 20 or newer; Python 3.11 or newer with `uv` and a `pipx` fallback for opt-in provisioning. |
| `memory` | The memory scopes (project files, portfolio) and the four guardrails. |
| `eval` | The evaluation gates (replay on pull requests; native-host runs for model upgrades). |
| `data_handling` | The doctrine behind the data-handling page: every flow that can leave the machine, with its consent basis. |
| `packs` | The ten packs and everything in the next table. |

**Fields of a pack**

| Field | What it declares |
| --- | --- |
| `order`, `display_name`, `cli`, `summary` | Install and display order, names, the exact strings the installer shows. Counts in a summary are derived with placeholders: the generator refuses a hand-typed number of agents, skills, workflows or packs in these fields. |
| `required`, `runtime` | Core is `required: true`. The runtimes a pack needs (`node`, and `python` for SEO). |
| `agents`, `personas` | The agent ids the installer registers, and the people-facing persona of each (name, role, description). |
| `skills`, `data` | Skill directories and data files the pack installs. |
| `install_layout`, `pack_dir`, `doctor` | `loose` copies agent directories into `.agents/skills/`; `packaged` copies one pack directory (`pack-<name>`) that holds its agents. `doctor` lists the agent files and required resources that `bmad-plus doctor` checks. |
| `uses_skills` | The skill ids a pack or a persona drives (see below). |
| `external_module` | Skills taken from a pinned npm package (see below). |
| `pipelines` | Ordered steps with a gate each (see below). |
| `intake` | The pack’s questionnaire file (see the intake page). |
| `governance`, `required_keys`, `optional_keys` | For OSINT: the lawful-basis gate and its templates, and the API keys. |
| `cohabitation_warning` | One sentence on how the pack overlaps another. It is shown by the installer and rendered as `- Cohabitation (<pack>): ...` under the registry facts of the spine and of the adapters. |
| `compliance_tags` | Frameworks a pack relates to (for example GDPR and EU-AI-Act for OSINT). |

<a id="uses-skills"></a>
## 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.

**registry.yaml, pack design (excerpt)**

```yaml
  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); ..."
```

<a id="external-module"></a>
## 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.

<a id="pipelines"></a>
## 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.

**Format of a pipeline, from the specification docs/specs/core-orchestration.md (a file of the source repository, not shipped in the npm package)**

```yaml
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 }
```

<a id="triggers"></a>
## 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).

<a id="generated"></a>
## What is generated, and the checks that keep it honest

**Commands in a BMAD+ source checkout**

| Command | What it does |
| --- | --- |
| `npm run build` | Runs `tools/build/generate.js` and writes the pack definitions in `tools/cli/lib/packs.js` and `src/bmad-plus/module.yaml` from the registry. |
| `npm run build:check` | Fails when the registry no longer reproduces those two files, when `product.version` differs from `package.json`, or when any declared path, skill, external module or intake is wrong. |
| `node tools/build/generate-adapters.js --adopt` | Regenerates `AGENTS.md` and the adapter files (CLAUDE.md, GEMINI.md, .cursor rules, .codex and .opencode files, CONVENTIONS.md). `--check` verifies them without writing. |
| `npm run check:counts` | Scans the shipped surfaces for hand-typed counts ("N agents", "N workflows", "N packs") and fails on any that contradicts what the registry and the files derive. A number is checked against its subject: 38 is right for Dev Studio workflows and wrong for agents. |
| `npm run check:triggers` | Validates the role triggers as described above. |

<a id="skills-anatomy"></a>
## 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.

**The Core skills**

| Skill | What it does | Driven by |
| --- | --- | --- |
| `bmad-plus-autopilot` | Nexus runs Discovery, Build and Ship with checkpoints; intake of every pack involved first. | Nexus (AP) |
| `bmad-plus-parallel` | Detects independent tasks, supervises them (launch, monitor, pause, restart, reallocate, escalate); contains the swarm section. | Nexus (PL) |
| `bmad-plus-swarm` | Moderator protocol for panel, jury and fanout swarms under a budget. | Nexus Parallel Supervisor |
| `bmad-plus-intake` | Protocol for `bmad-plus intake`: plan, ask a few questions, record, render. | Any pack with an intake; autopilot |
| `bmad-plus-uat` | Human acceptance recipe: write the spec, build the page, read, triage, gate. | Sentinel (RB, RR, RG); autopilot |
| `bmad-plus-sync` | Protocol for checking the installed framework once per session; for maintainers, packets to review upstream changes (no automatic upstream merge). | Anyone; maintainers |

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.

<a id="extend-with-maker"></a>
## 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.

**What Maker writes**

| File | Content |
| --- | --- |
| `agents/agent-<name>/SKILL.md` | The agent: overview, identity, communication style, principles, capabilities table with two-letter codes, activation steps. |
| `agents/agent-<name>/bmad-skill-manifest.yaml` | Name, display name, title, icon, capabilities, role, identity, pack, canonical id. |
| `pack-definition.yaml` | A ready-to-merge snippet for the `packs:` table of `registry.yaml` (order, display name, icon, CLI entry, runtime, summary, agents, personas, skills, install layout, compliance tags, required keys). |
| `INTEGRATION.md` | Integration instructions: files to copy, the registry entry to add, the help-index line, the regenerate-and-check sequence, a test install. |

> **Note · Maker’s integration note follows the registry** The `INTEGRATION.md` that Maker writes is registry-first: it tells you to add the entry from `pack-definition.yaml` under `packs:` in `registry.yaml`, never to edit the files generated from it (`tools/cli/lib/packs.js`, the pack metadata of `src/bmad-plus/module.yaml`, `AGENTS.md` and the other adapters), to add a line to `src/bmad-plus/module-help.csv` by hand, to regenerate, and to run the drift checks. The steps below follow the same sequence.

1. **Create and validate the agent** Ask Maker for `CA`, answer its discovery questions, validate the design table, then run `VA` on the result.
2. **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. **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. **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. **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.

<a id="example-registry-ask-maker-agent"></a>
### Design a team agent with Maker

Use with the Maker pack installed. The package is written to `_bmad-output/ready-to-integrate/`; it changes nothing else.

**In your AI assistant**

```text
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.
```

**What you should get** One batch of questions, a design preview you approve, then `_bmad-output/ready-to-integrate/` with the agent’s `SKILL.md`, its manifest, a pack snippet and an integration note, followed by the validation checklist (format, manifest fields, unique capability codes, trigger quality). Nothing is installed or registered until you do it.

**See also**

- [How BMAD+ works](https://bmad-plus.rochetta.fr/docs/concepts/how-bmad-plus-works/)
- [Intake: ask first](https://bmad-plus.rochetta.fr/docs/concepts/intake/)
- [The Maker pack](https://bmad-plus.rochetta.fr/docs/packs/maker/)
- [The Design pack](https://bmad-plus.rochetta.fr/docs/packs/design/)
- [Reference: adapters](https://bmad-plus.rochetta.fr/docs/reference/adapters/)
- [Data handling](https://bmad-plus.rochetta.fr/docs/security/data-handling/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Concepts](https://bmad-plus.rochetta.fr/docs/concepts/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)