bmod-toolsmith

[bmod]
code = "toolsmith"
version = "6.13.0-next"
update_source = "github:bmad-code-org/BMAD-METHOD/skills"
skills = ["bmad-toolsmith", "bmad-eval"]
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
pre_install_message = ""
post_install_message = """Toolsmith is installed.
Ask for Smithy to build a skill, optimize or convert a skill to bmad compliance, an agent persona with or without memory or a module; he starts by asking what it is for.
bmad-eval measures whether a skill works: baseline, variant, quality and trigger runs."""

# How a build runs

Read this when the user asks how Smithy will build something, or which way of working fits them. An approach is the path from a wish to a skill. Every path starts with the same discovery conversation and the same read-back, and ends in the same ship step: the quality lenses run over what Smithy wrote and he fixes what they find, the validators run, and a trigger eval is offered. The approach is proposed in the read-back; lean is the default, and the user can name another up front.

| Approach | What happens | Fits when |
|---|---|---|
| Lean | Smithy draws out purpose, user and output, proposes the shape, writes the smallest skill that does the job, tries it on one real input, then ships. | The default. The user wants the skill and will judge it by using it. |
| Scaffold and guide | Smithy lays out the folder, frontmatter, `bmod.toml` and empty files, points at the canon, and leaves the writing to the user. The ship step validates only. | The user wants to write the skill themselves and only needs the shape right. |
| Eval-first | Trigger cases and output checks are written first, in the skill's `evals/` folder. Smithy builds until `bmad-eval` passes them, and the ship step records the run. | The output can be checked objectively (file transforms, extraction, generated code, fixed steps) and the user wants proof, not a draft. |
| Skill-creator loop | Draft, run with and without the skill, grade, change, run again, then optimize the description for triggering. BMad adds the canon, customization and the `bmod.toml` step to the loop. | The user wants to iterate on measured results, or has a skill-creator `evals.json` to start from. |
| From session logs | Smithy reads transcripts or session logs, finds what was asked for repeatedly, what worked and what was corrected, proposes a skill, and builds it the lean way. | The user says "make a skill from my sessions" or keeps doing the same thing by hand and wants it captured. |

Eval-first and the skill-creator loop share one loop: cases, run, grade, change, rerun. They differ in who writes the cases first and whether description optimization runs. Suggest one of them only when the output can be checked; writing style and coaching cannot be graded well, so those skills take the lean approach and a trigger eval.

Smithy does not test every idea against the bare model first. A skill that saves retyping a format, preference or convention is warranted by that alone. He runs the trigger phrase bare only when the skill claims to teach the model something, the model it will run on is fixed, and the user has not asked for speed or autonomy; for a skill that will be distributed, the comparison belongs to `bmad-eval`'s baseline mode on the user's own cases.

# Customizing a skill without forking it

Read this when the user asks how a team changes a skill's behavior, what `customize.toml` is, where overrides live, or why Smithy told them to use `bmad-customize`.

A skill that teams will adjust ships a `customize.toml`: a `[workflow]` table for a skill, an `[agent]` table for an agent. It declares what can change: steps to run before or after activation, standing facts to hold for the run, a hook to run on completion, an output path, and the skill's own settings, each commented with when to override it. The body reads every declared value, so a value declared but hardcoded in the body is a defect: every override would be a silent no-op.

Overrides never touch the skill. They live in the project: `_bmad/custom/<skill>.toml` for the team, `_bmad/custom/<skill>.user.toml` for one person, kept out of version control. The three layers merge when the skill activates: scalars override, arrays append, arrays of tables merge by `code` or `id`. So a team can add an activation step, a format or a menu item and the skill's next update does not lose it.

One reader, one writer. The project's `resolve_customization.py` reads the layers for every skill. The `bmad-customize` skill writes the override files, for any skill that has a `customize.toml`. A skill never writes its own overrides, never ships its own merge script, and never carries a second code path for when BMad is absent; it says in one line "to change X, invoke `bmad-customize`", and offers to install it when missing. Smithy's review flags a skill that does otherwise.

What customization is not: boolean toggles (a switch means the author never decided), persona fields in a workflow, or a settings concept of the skill's own. Project-wide values such as the output folder are core config, read with `resolve_config.py`, not per-skill customization.

# Writing the description

Read this when the user asks why their skill does not fire, fires on the wrong things, or how to write the description.

The description is the skill's only trigger. The agent's router reads it, with every other installed skill's, and decides whether to load the skill. Nothing in the body helps with that decision.

It has two parts: a five-to-eight-word summary of what the skill does, in the third person, then `Use when the user says ...` with the quoted phrases a user would actually type. Every installed description is paid on every session, so it stays that short; 1024 characters is the hard ceiling, not a target. Most BMad skills are asked for explicitly, so explicit phrases are the default; a skill that must fire unasked describes the context instead, such as "when code imports the anthropic SDK". One phrase per situation; a synonym stack adds length and no reach. Describe the user's problem, not the tool's symptom: "release notes from merged PRs", not "changelog generation".

Near misses are requests that share words and domain but belong elsewhere: debugging a workflow versus building one, critiquing a brief versus writing one. Smithy asks for them during discovery and the trigger eval tests them. When a skill takes a sibling's requests, the description adds `Not for ...` naming that sibling; without a collision it stays at two parts.

An agent is the exception to keeping it short. Its `Use when` starts with the user asking for it by name, then lists the phrases of every capability built into it, since nothing else triggers those capabilities. The summary stays short; the list does not.

A skill only ever called by name, such as a slash command, gets a one-line description and, where the harness supports it, `disable-model-invocation: true`, so it never competes in the router.

A description is revised from eval failures by changing its situations and boundaries, never by pasting a failed query's words into it. Smithy offers a trigger eval at the end of every build (`help/evals.md`).

# Progressive disclosure and size

Read this when the user asks how long a skill should be, why Smithy split theirs into files, or what progressive disclosure means.

A skill is paid for every time it runs. The entry file, `SKILL.md`, is read on every invocation; a reference is read only when the branch that names it is reached. So the question is never "how big is the skill" but "how much does one run load". A plain skill's entry aims near 800 tokens, an agent's near 1,200. A complex workflow is the right size at any total when each branch sits in its own file and loads only when reached; the same workflow loaded whole is too big at half the size.

The rules Smithy follows and the review checks:

- Carve by relevance, not size. What only some branches need goes in a reference; what every run needs stays in the entry. A piece too small to repay the indirection stays inline, and a skill small enough to be one file is one file.
- One level deep. The entry names a reference; a reference never names another. The entry carries a short routing map when there are several.
- Name a reference when its branch is reached, never ahead of it: "read `references/<topic>.md` fully and follow it".
- Every file a model reads is held to the same standard as the entry: each reference, each capability file, each template a model reads as text. A skill judged by its entry alone has most of its text unjudged.
- The description is the only place "when to use" lives; the body never repeats it.
- Cut what a capable model would do unasked. Instructions for exotic cases are paid on every run and the case is paid only when it occurs.

Smithy's review mode measures tokens per file and says what one run loads; its leanness lens proposes the smallest version and what it would change.

# Scripts in a skill

Read this when the user asks whether something should be a script, why Smithy wrote one, or how scripts in a skill are run.

A script does work that has one right answer per input: parsing, counting, resolving paths, validating structure, rendering a template, diffing, generating random values. Prose does work that turns on meaning: judgment, tone, what to do with a result. A line on the wrong side is a defect the review catches: prose counting tokens or checking structure is paid on every run and done differently each time; a script deciding what a sentence means breaks when the phrasing shifts.

How a script is written: Python with a PEP 723 header (`requires-python = ">=3.11"`, dependencies listed), `--help`, JSON on stdout when the agent reads the result, a non-zero exit with a reason rather than an error left for the agent to notice, standard library first. A `unittest` test sits beside it at `scripts/tests/test_<name>.py`. No model ids anywhere; users run any model. No network unless the docstring says why.

How a script is run: always `uv run <path>`, with the skill's own scripts as `uv run {skill-root}/scripts/<name>.py` and the project's runtime scripts as `uv run {project-root}/_bmad/scripts/<name>.py`. Never `python`, `python3` or `pip`; `uv run` reads the header and provides the dependencies, so the user installs nothing. Never a bare `scripts/x.py`, which resolves from wherever the agent happens to be.

Tests assert what a script produced, never what a model wrote or what a prompt file says.

# Evals in detail

Read this when the question is about `bmad-eval`, trigger accuracy, or whether a skill works. An eval runs a skill through the user's own agent runtime in a clean working directory and reports what came back. Smithy offers one at the end of every build and reaches `bmad-eval` from his menu, so a user usually meets it through him. Call it directly when the user has the skill and the cases and wants the numbers.

## The four modes

| Mode | Answers | Recommend when |
|---|---|---|
| Baseline | Does the skill beat the bare model on the same input? | The user asks whether the skill is worth keeping, or as the release check. A skill the bare model matches should be retired, not patched. |
| Variant | Does a section earn its place, or does a stripped or prior version do as well? | The user cut or changed something and wants to know whether it mattered. |
| Quality | Does the output meet the case's rubric? | The user has a rubric for what good output looks like and wants each case graded against it, with no partial credit. |
| Trigger | Does the description fire on the requests it should and stay quiet on the rest? | The skill does not trigger, triggers on the wrong things, or has just been built. |

## What a trigger eval is

The description is a skill's only trigger: the router reads it and loads the skill or moves on. A trigger eval runs a set of queries through the real runtime and records whether the skill loaded. Each query is marked should-trigger or should-not. The should-not queries matter most when they are near misses: requests that share words, domain and phrasing with the real ones but belong elsewhere, such as debugging a workflow versus building one, or critiquing a brief versus writing one. A should-not query that obviously belongs to another skill teaches nothing, because any description already handles it. When failures come back, the description is revised by changing its contexts and boundaries, never by pasting a failed query's words into it, and the eval runs again. `bmad-eval` also runs a bounded optimization loop that improves the description against a held-out test set so the rewrite does not overfit to the cases it is graded on.

## How many runs

Firing and output are probabilistic, so one run proves little. Three runs per case is the floor; more when the user wants a variance figure or a difference between two versions. A pass that holds on every run is a pass; one that holds on one run out of three is a lead to follow.

## Which harness runs it

An eval runs through the agent CLI the user is already working in: Claude Code, Codex or another. `bmad-eval` ships no list of harnesses. The first time it runs in a project, the agent works out four facts about its own CLI (the command for one non-interactive run, the folder it reads skills from, the env vars the run needs, and the files that keep it logged in) and records them in `bmad-eval`'s customization through `bmad-customize`, where the user can read and change them. Each case then runs in a clean working directory with a copy of the skill and a fresh HOME, so the user's own skills, memory and settings do not leak into the result. The run bypasses the CLI's permission prompts, because nobody is there to answer them; the agent says so when confirming the run, and a user who wants the run contained wraps the recorded command in a sandbox.

## Where runs land

Every run is a timestamped folder in an eval-reports folder inside the project's output folder (changeable in `bmad-eval`'s customization), one case per subfolder with its prompt, transcript, working directory and grades. Runs are never deleted or overwritten, so a skill's history stays comparable. `bmad-eval` tells the user where the run is when it finishes. A skill's cases live beside it, in its `evals/` folder, and a skill-creator `evals.json` can be converted into them.

# Toolsmith knowledge

This document covers the skills of the `toolsmith` module: what each one gives the user, when to recommend it, and what to offer next. The topic files in this folder go deeper; each is small and named for its subject, so read the one the question is about.

## What the module is

Toolsmith is for people who author skills, agents and modules, not for people who only use them. It replaces the BMad Builder module. One agent, Smithy, builds and changes BMad content from a conversation; one skill, `bmad-eval`, measures whether the result works. Recommend Toolsmith whenever the user wants to make, change or judge a skill, whatever they call it: a skill, an agent, a persona, a workflow, a custom command, a prompt they keep pasting, a module.

## What it needs

Smithy runs inside a project where `bmad` is set up (`_bmad/` exists); without it he offers setup first. `uv` must be installed, since every script runs as `uv run`. A skill Smithy writes straight into the folder the user's agent reads from is live at once but is not tracked by the skills CLI, so updates to it are the user's own; one installed later from a repo with `npx skills add` is tracked.

## The skills

| Skill | For | When to recommend |
|---|---|---|
| `bmad-toolsmith` | Smithy, the Toolsmith. Builds a skill, agent or module from a conversation about what it is for, who uses it and what it produces. Shows a read-back (name, description, shape, registration, approach, location, files) and writes nothing until the user approves it; every line can be changed. Picks the shape as a conclusion of the conversation, never as a menu. After a build the quality lenses run on their own and Smithy fixes what they find before handing over. Also edits, converts, reviews, packages, validates and migrates skills that exist, and offers evals at the end of every build. | Any request to create or change a skill, agent, persona or module; to review or judge one; to package skills; to convert something from another tool; to migrate an old module. Ask for Smithy by name or describe the thing wanted. |
| `bmad-eval` | Runs a skill's evals and reports what they show, in four modes: baseline (does the skill beat the bare model), variant (does a stripped or prior version do as well), quality (does the output meet its rubric), trigger (does the description fire on the right requests and stay quiet on the rest). Smithy reaches it from his menu and at the end of a build, so a user rarely needs to call it directly. | The user asks whether a skill works, is worth keeping, triggers reliably, or whether a change made it better or worse. Call it directly when the user has a skill and cases already and wants numbers, not a conversation. |

## Start here

- "Make me a skill", "build an agent", "I need a module", "create a persona", "write me a custom command" → `bmad-toolsmith`. Smithy asks what it is for first; the user does not need to know what shape they want (`help/shapes.md`, `help/approaches.md`).
- "Turn this chat into a skill", "we keep doing this by hand", "I keep pasting this prompt" → `bmad-toolsmith`. The conversation is the material; Smithy mines it before asking anything.
- "Make a skill from my sessions", a transcript, session logs → `bmad-toolsmith`, the from-logs approach.
- "My skill does not trigger", "it fires on the wrong things" → `bmad-toolsmith` for the fix, or `bmad-eval` in trigger mode when the user wants the measurement first. A trigger eval, not a rewrite by feel, settles it (`help/evals.md`).
- "Is this skill any good", "review this skill", "how could it be smaller" → `bmad-toolsmith`, review mode. Findings in chat and a markdown file; nothing fails or blocks (`help/modes.md`, `help/how-to-review.md`).
- "Does my skill actually help", "is it worth keeping", "did my change make it better" → `bmad-eval`, baseline or variant mode (`help/evals.md`).
- "Which agent runs the eval", "can I run evals from Codex", "is the eval sandboxed" → `help/evals.md`, the harness section.
- "Package these", "make this a module", "ship these together" → `bmad-toolsmith`, package mode.
- "I have an old module with `module.yaml`", a setup skill, a help CSV → `bmad-toolsmith`, migrate mode. It shows the plan and waits for approval before changing anything.
- "Convert my Cursor rule", "turn my GPT into a skill", "port this slash command", "make this skill work with bmad" → `bmad-toolsmith`, convert mode (`help/how-to-convert-external.md`).
- "Is this a valid bmod", "check my skill" → `bmad-toolsmith`, validate mode.
- "Fix", "change", "extend", "add a step to" an existing skill → `bmad-toolsmith`, edit mode.
- "What makes a good skill", "how long should a skill be", "what is progressive disclosure", "how do I write the description" → the `craft-*` topics below; answer from them, and offer Smithy's review mode on a skill they have.
- "Should this be its own module", "how do I add a skill to the method", "what does registering with bmad give me" → `help/registration.md` and `help/how-to-add-to-module.md`.
- "Where is the official spec", "how does Claude Code / Codex / Cursor load skills" → `help/references.md`.

## When not to recommend it

- Implementing application code, a feature or a bug fix is `bmad-build`, even when the user says "build".
- A one-off request needs no skill. When the user wants something done once, do it; Smithy himself asks whether a skill is warranted and says so when it is not. A skill that saves retyping a format, preference or convention is warranted by that alone.
- Running or using an installed skill is not Toolsmith work; invoke that skill.
- Questions about BMad itself go to the `bmad` skill.

## Where things land

Smithy proposes where a new skill goes in the read-back and the user confirms or changes it: the project's `skills/` source folder when the project is a skill repo, otherwise the folder the user's agent reads skills from, so the skill is live as soon as it is written, or the user's own skills folder when it is for them everywhere. The read-back also proposes how the skill registers with BMad, guessed from what is installed: its own module record, a member of an installed module, or a plain skill that help and update checks never see; the user picks (`help/registration.md`). Review reports and eval runs go in an eval-reports folder inside the project's output folder, one timestamped file or folder per run. Both locations can be overridden in the skills' customization files; the module asks no setup questions. At the end of a build Smithy tells the user where the skill is, whether it is already live, and how it is registered.

## After a skill finishes

| Just finished | Offer next |
|---|---|
| Smithy built a skill | The lenses have already run and their defects are fixed; Smithy said what changed. Next: the trigger eval he offers, then one real request to try. A baseline eval when they want proof the skill beats the bare model. For a new module record, `bmad setup <code>`. |
| Smithy edited, packaged or migrated a skill the user owns | A review, since the lenses do not run unasked over a skill Smithy did not write. Then the trigger eval if the description changed. |
| A review report | Edit mode for the findings the user accepts. The report is advice; the user picks. |
| A trigger eval with failures | Smithy revises the description from the failures and runs it again (`help/evals.md`). |
| A baseline the skill no longer wins | Retire the skill or rethink it; patching a skill the bare model matches is wasted work. |
| A migration | It converts in place, then validates and ships. Offer setup next, since the module's config questions may have changed. |

## More detail

Each topic file below sits in this folder and goes deeper on one subject. Read one only when the question is about that subject, using the path the knowledge script lists for it.

| Topic file | Read when the user asks about |
|---|---|
| `help/shapes.md` | What kinds of thing Smithy can build, in one table; which one their need lands in. Each shape then has its own file. |
| `help/shape-plain-skill.md` | A plain skill: its files, what goes in `SKILL.md`, when it gets a `customize.toml` or a `bmod.toml`. |
| `help/shape-agent.md` | An agent persona: how its identity, menu and capabilities are defined, how a team customizes it, how it joins a module's roster. |
| `help/shape-memory-agent.md` | A memory agent (Continuity of Self): the sanctum, how its memory is laid out and tended, First Breath, Pulse. |
| `help/shape-rendered-skill.md` | A skill whose steps teams switch on and off through customization. |
| `help/shape-script-utility.md` | A skill that is mostly scripts, and the rules those scripts follow. |
| `help/shape-single-skill-module.md` | One skill that is its own module: what the record adds and when it is worth it. |
| `help/shape-multi-skill-module.md` | A module of several skills: the record folder, roster, help and retired list. |
| `help/registration.md` | Whether a skill joins a module, gets its own record or stays outside the registry; what each gives; contributing to the BMad Method module versus extending it in a project. |
| `help/approaches.md` | How a build runs: lean, scaffold and guide, eval-first, the skill-creator loop, from session logs; which fits the user's situation. |
| `help/modes.md` | Working on a skill that exists: edit, convert, review, package, validate, migrate; what each does and the phrase that reaches it. |
| `help/evals.md` | `bmad-eval` in depth: what each mode answers, what a trigger eval is, why near misses matter, how many runs, which harness runs it and how that is recorded, where runs land. |
| `help/naming.md` | What to call a skill or module: why a prefix of their own, what `bmad-` means, how agents and module records are named. |
| `help/craft-progressive-disclosure.md` | How big a skill should be, what loads when, why a complex workflow is carved into files loaded only when reached. |
| `help/craft-description.md` | Writing the description that makes a skill fire: its two parts, quoted trigger phrases, when to name a sibling, hand-invoked skills. |
| `help/craft-scripts.md` | When a skill should script something instead of saying it, and how scripts are written and run. |
| `help/craft-customization.md` | How a skill is customized without forking it: the `customize.toml` surface, the override files, who reads and who writes them. |
| `help/how-to-personal-skill.md` | Walkthrough: a skill for the user's own use, start to live. |
| `help/how-to-add-to-module.md` | Walkthrough: a skill that joins a module, their own or the BMad Method. |
| `help/how-to-convert-external.md` | Walkthrough: a Claude, Codex or Cursor skill, rule, GPT or slash command brought to BMad. |
| `help/how-to-memory-agent.md` | Walkthrough: a memory agent from the first question to its first waking. |
| `help/how-to-review.md` | Walkthrough: reviewing a skill someone else wrote and acting on the findings. |
| `help/references.md` | The open skill specification and the skill documentation of the harnesses users run, with links. |

## When this document is not enough

For a `toolsmith` question these files and the installed skills cannot answer, say so rather than guess, and offer to ask Smithy directly: his files under `bmad-toolsmith/` are the authority on how he behaves.

# How to: a skill that joins a module

Read this when the user wants to add a skill or agent to a module: their own, their organisation's, or the BMad Method. Settle which case it is first.

## Your own or your organisation's module

1. Tell Smithy which module, or let him guess from the prefix: a name carrying an installed module's prefix, or a skills repository with a `bmod-<code>/` record, points him there.
2. The read-back shows registration as "member of `bmod-<code>`", the name with the module's prefix, the location beside the module's other skills, and the files: the skill, its small `bmod.toml` naming the record, and the edits to the record itself: the skill list, a help row, and a roster entry when it is an agent.
3. Smithy builds it, runs the lenses, and validates the module's manifests. For an agent, party mode and `bmad` see it through the roster.
4. If the module is installed from a repository, the new skill ships when that repository is pushed and the users run `bmad setup`; a skill written into the installed copy is overwritten by the next update, so build it in the source repository.

## Contributing to the BMad Method

The method module is `bmod-method` in the BMAD-METHOD repository. A contribution is a skill under that repository's `skills/` folder with a `bmad-` name and a `bmod.toml` naming `bmod-method`, built in a clone or worktree of that repository and offered as a pull request. Smithy treats a clone of it as a skills repository and registers the skill as a member.

## Extending the method in your project

Do not add to the installed method record; the next update overwrites it. Make your own module with your own prefix (`help/naming.md`) whose skills require or recommend the method skills they build on. `bmad` help recommends your skills beside the method's, and updates leave both alone.

# How to: bring an outside skill, rule or prompt to BMad

Read this when the user has something from another tool: a Claude Code or Codex skill, a Cursor rule, a GPT, a slash command, a system prompt they keep pasting.

1. **Point Smithy at it**: the file, folder or pasted text. He reads it whole and extracts the outcome, who consumes it, the triggers the author meant, the know-how a model would not have, and any scripts.
2. **He drops the host's mechanics**: frontmatter keys another tool owns (`globs`, `alwaysApply`, `argument-hint`, `model`), slash-command syntax and `$ARGUMENTS`, GPT conversation starters, and the instructions every model follows unasked (be helpful, think step by step, format as markdown). What prevents a failure stays.
3. **Discovery fills the gaps** the source never said, usually the consumer, the near misses, and the name, since outside skills are named for their host. Registration is asked like any build.
4. **Two paths.** Rebuilt beside the source: a new BMad skill in the right shape, with what did not carry over listed; the source is left as it was. Or in place, when the user says "make this skill work with bmad": the same folder, the description rewritten to the canon, paths and config reads brought to BMad's conventions, and a `bmod.toml` when they want it registered.
5. **Ship as usual**: lenses, validation, an offered trigger eval.

What an outside skill most often gains: a description that triggers reliably, paths that travel between machines, configuration read from the project rather than hardcoded, and registration so `bmad` can recommend and update it. A skill in the agentskills.io format already has the right frontmatter; BMad uses `name` and `description` and treats `allowed-tools` as the host's concern (`help/references.md`).

# How to: a memory agent

Read this when the user wants an agent that remembers them between sessions and asks what building and living with one looks like.

1. **The test first.** Smithy asks whether memory is warranted: used daily for a month, would the thirtieth session differ from the first? If not, he proposes a stateless agent with standing facts instead. The gradient comes as questions, not a menu: remember you between sessions; be given material to keep (transcripts, recordings, notes); be taught new things over time; work on its own on a schedule. Each yes adds a layer.
2. **Read-back.** The agent's name, or an empty name when it should name itself at First Breath; its mission at the species level, specific to this kind of agent; the territories First Breath will explore with you; its built-in capabilities; registration and location like any build.
3. **What Smithy writes.** A short bootloader `SKILL.md`, a `customize.toml` with the identity, a First Breath reference, a capability file where there is know-how to hold, the sanctum seed templates, and two scripts, `wake.py` and `init-sanctum.py`, unchanged from the shape.
4. **First waking.** The agent finds no sanctum and runs First Breath: it builds the sanctum, then opens by asking what to call you. Your reply sets your name and the language. It learns you through conversation, not a form, writes as it goes, and settles its own name and mission. Anything unfinished waits in `memory/pending.md` for next time.
5. **Every later waking.** It reloads its five identity files and a map of its memory, raises what is pending, tends its memory when session notes have built up, and carries on as the same self. You can hand it material to keep, teach it a capability, or ask it to review what it remembers.

Where memory lives: `_bmad/memory/<skill>/` in the project, as small files by subject (`help/shape-memory-agent.md`). The agent writes nothing about you from config; everything comes from talking to you.

# How to: a skill for yourself

Read this when the user wants a skill for their own use and asks what will happen. Walk them through it in these terms.

1. **Say what you want**, in a sentence or a conversation. Smithy mines it first and asks only for what is missing, one or two questions at a time, each with the answer he would guess so you can just confirm. The things he needs: what it gets done and for whom, who consumes the output and what must be true of it, the phrases you would type to reach it and the nearby requests it should ignore, where the know-how lives, whether the output can be checked, how it registers with BMad, and where it will run.
2. **Approve the read-back.** Name (with your own prefix, not `bmad-`), one line on purpose, the description as it will ship, shape, registration, approach, where it will live, and the files. Change any line; nothing is written before you say yes. For a personal skill the usual answers are plain shape, plain registration, and the folder your agent reads skills from, so it is live the moment it is written. Say so if you want it in `~/.claude/skills` or `~/.agents/skills` for every project.
3. **Smithy writes it**, tries it on one real input if you gave one, and runs the quality lenses over every file. He fixes the defects they find and tells you what changed.
4. **Hand-off.** Where it is, that it is live, and one request to try. He offers a trigger eval, worth taking for any skill you expect to fire on its own, and a review.

Afterwards: "change", "fix" or "extend" the skill reaches edit mode. If you later want `bmad` to recommend it or check it for updates, convert mode's in-place path adds a record (`help/registration.md`). A skill written straight into your agent's folder is not tracked by the skills CLI; updates are yours to make.

# How to: review a skill

Read this when the user has a skill, theirs or someone else's, and wants to know whether it is any good, how to make it leaner, or why it misbehaves.

1. **Point Smithy at the folder.** Review mode reads nothing but the skill; it works on an installed skill, a skill in a repository, or one pasted into a folder.
2. **Pre-pass.** A script measures it: tokens per file and what one run loads, the description's length and parts, whether frontmatter is valid, which scripts have headers and tests, every path that does not resolve, calls that should be `uv run`, scripts that touch customization files, and how it is registered.
3. **Five lenses**, run as parallel readers over every file a model would read: architecture (files, paths, shape, registration), determinism (what should be a script and what should be prose), leanness (what a capable model would do unasked, duplication, the smallest version), customization (declared values that reach nothing, overrides that cannot land), trigger (the description against the near misses).
4. **Findings**, in chat two lines each and in a markdown file in the eval-reports folder, merged, deduplicated and ordered by severity, each naming the file it is in and the fix. Nothing fails or blocks; the report is advice.
5. **Act on it.** Edit mode applies the findings the user accepts. For cuts the user is unsure about, a variant eval shows whether the section earned its place (`help/evals.md`).

For a skill Smithy just built, the lenses already ran and the defects are fixed; review is for skills he did not write, or for a second opinion later.

# Working on a skill that exists

Read this when the user has a skill, prompt or module already and wants something done to it. A mode starts from an existing skill. Convert and migrate end in a build; edit may change the shape; the rest leave the skill as it is. Every mode that writes files ends in the same ship step as a build.

| Mode | What the user gets | The phrase that reaches it |
|---|---|---|
| Edit | Smithy reads the skill, agrees the change with the user, applies it, and keeps the shape unless the change needs another. | "Change", "fix", "extend", "add a step to", "make it smaller". |
| Convert | A skill, prompt, rule or command from another tool or format, rebuilt as a BMad skill in the right shape, with what did not carry over listed. A skill that already exists can instead be brought to BMad in place, as a single-skill module when the user wants one. | "Convert my Cursor rule", "turn my GPT into a skill", "port this slash command", "make this prompt a skill", "make this skill work with bmad". |
| Review | A list of findings, in chat and as a markdown file in the reports folder: pre-pass measurements, then five lenses (architecture, determinism, leanness, customization, trigger) read by parallel reviewers, each finding with where it is and its fix. Nothing fails; the user decides what to act on. | "Review this skill", "is this any good", "analyze it", "how could it be leaner". |
| Package | One skill or several wrapped as a module: a single-skill module when it is one, a multi-skill module with roster and help when it is several. | "Package these", "make this a module", "ship these together". |
| Validate | The checks that gate a skill: manifests, file references, frontmatter, and a trigger eval when a case suite exists. Pass or fail, with each failure named. An old-format module (`module.yaml`, a setup skill, a help CSV) fails and names migrate as the fix. | "Validate", "check my skill", "is this a valid bmod". |
| Migrate | An old-format module converted in place to a bmod: the record folder, roster from its agents, help from its CSV, a `bmod.toml` per skill, a retired list for the names that went. Smithy shows the conversion plan and waits for approval, lists what it could not convert, removes the old files, then validates and ships. | "I have an old module", `module.yaml`, "my setup skill", "move my module to the new format". |

After a review, offer edit mode for the findings the user accepts. After a migration, offer `bmad setup` for the module, since its configuration questions may have changed.

# Naming skills and modules

Read this when the user asks what to call a skill, an agent or a module, or whether to start a name with `bmad-`.

## Use a prefix of your own

Name skills after the org or module they belong to: `acme-release-notes`, `acme-agent-reviewer`, with the module record `bmod-acme`. A prefix of your own does three things. It tells custom from core BMad at a glance, in a skills folder, a `/` autocomplete list, or a session log. It keeps a module's skills sorted together, so adding, removing and updating them is one glance. And it makes observability cheap: a trace or a usage report that groups by prefix separates your skills from the ones BMad ships without any further tagging. Smithy asks for the name during discovery and proposes one with your prefix; the choice is yours.

## What `bmad-` means

`bmad-` marks a skill shipped by the bmad-code-org. Its modules name skills `bmad-<code>-<skill>` and agents `bmad-<code>-agent-<name>`, with the code left off for core (`bmad-prd`, `bmad-agent-dev`). A custom skill named `bmad-` reads as official, collides with a future core skill, and hides in listings among the ones you did not write. Use your own prefix instead.

## Modules

A module's record folder is always `bmod-<code>`; that is how `bmad` finds it, in any repo. Its skills carry the code as prefix, and its agents add `-agent-` after the code. Renaming a skill changes how it is invoked, so when packaging existing skills Smithy offers the rename and the user decides.

# Outside references

Read this when the user asks where the official skill specification is, how a particular harness loads skills, or wants to read the sources BMad's conventions build on. Give the link and one line on what it covers; do not fetch pages to answer questions these help files already answer.

| Resource | What it covers |
|---|---|
| Agent Skills specification: <https://agentskills.io/specification> | The open `SKILL.md` format BMad skills follow: `name` and `description` rules, optional keys, the `scripts/`, `references/` and `assets/` folders, progressive disclosure, the 500-line guidance. BMad uses `name` and `description` only and treats `allowed-tools` as the host's concern. |
| Agent Skills overview: <https://agentskills.io/> | What skills are and which agents support the format. |
| Anthropic, Agent Skills: <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview> | The three-level loading model (metadata, instructions, resources on demand) and where skills work across Anthropic products. |
| Anthropic, skill authoring best practices: <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices> | Concise writing, degrees of freedom, third-person descriptions, one-level-deep references, building evaluations first. Several of BMad's canon rules are rewrites of these in BMad's terms. |
| Anthropic skills repository: <https://github.com/anthropics/skills> | Example skills and the skill-creator skill whose eval loop the skill-creator approach follows. |
| Claude Code skills: <https://code.claude.com/docs/en/skills> | Where Claude Code loads skills from, its frontmatter extensions such as `disable-model-invocation`, slash invocation, and dynamic context. |
| Codex and ChatGPT skills: <https://learn.chatgpt.com/docs/build-skills> | How Codex loads skills from `.agents/skills`, explicit versus implicit invocation, and its description budget. |
| Cursor rules: <https://cursor.com/docs/context/rules> | The `.mdc` rule format Smithy converts from: `alwaysApply`, `description` and `globs`. |
| The `skills` CLI: <https://github.com/vercel-labs/skills> | `npx skills add`, the installer BMad uses, with its agent paths and options. |
| Skills directory: <https://skills.sh/> | A directory of installable skills, useful for seeing what exists before building. |
| Superpowers: <https://github.com/obra/superpowers> | A skills-based methodology whose writing-skills guidance informed some of BMad's rules. |

BMad's own conventions are in these help files and in Smithy's canon; they do not require any page above to be read.

# Registering a skill with BMad

Read this when the user asks whether a skill should be its own module, join one, or stay a plain skill; what registering gives; or how to add to the BMad Method. Smithy guesses the answer from what is installed and puts it in the read-back as its own line, so the user always sees and can change it.

## The four choices

- **Plain skill, outside the registry.** No `bmod.toml`. It still works, and it can still read BMad config and customization. But `bmad` help never recommends it, setup never sees it, and update checks skip it. Right for a personal skill or a one-off the user keeps by hand.
- **Single-skill module.** Its own record in the same folder. Setup asks its questions, help recommends it, updates are checked, other skills can require it. Right for a lone skill that maintains a project file, has a path a team would set, or that the user wants `bmad` to know (`help/shape-single-skill-module.md`).
- **Member of an existing module.** A small `bmod.toml` naming the record, plus edits to the record: the skill list, a help row, a roster entry for an agent. The skill takes the module's prefix and lives beside its other members.
- **First skill of a new module.** A record folder plus the member file. Usually reached through package mode once two or more skills exist.

## How Smithy guesses

No `_bmad/` and nothing said about BMad: plain. `_bmad/` present and a skill that reads config, maintains a project file, has a settable path, or that the user wants recommended: single-skill module. A skills repository with a record, a module the user named, or a name carrying an installed module's prefix: member. Several skills described: a new module. The guess is one line in the read-back with its consequence; the user confirms or changes it.

## Adding to the BMad Method

Two different things. Contributing a skill to the official method module means a pull request to the BMAD-METHOD repository: the skill lives under its `skills/`, takes a `bmad-` name, and its `bmod.toml` names `bmod-method`. Extending the method inside a project means the user's own module with their own prefix, whose skills require or recommend the method skills they build on; it never takes a `bmad-` name and never edits the installed method record, which the next update would overwrite (`help/how-to-add-to-module.md`).

## After the fact

A skill that was built plain can be registered later: convert mode's in-place path adds the record, and package mode wraps several. A skill wired to BMad with no record shows up in a review as "registered nowhere".

# Agent with capabilities

Read this when the user asks how an agent persona is defined, what a capability is, how a team changes an agent, or how an agent joins a module. Smithy is this shape himself.

## Identity

An agent is a skill named `<prefix>-agent-<name>` whose `customize.toml` carries an `[agent]` table: `name`, `title`, `icon`, `role`, `identity`, `communication_style` and `principles`. The persona is what the agent judges by when no capability fits, so it is written in the agent's own voice, one or two sentences each, with three to five principles that are stances rather than slogans. On activation the agent resolves that table, runs any steps a team added before or after, loads standing facts, reads config, then greets with its icon, which it keeps on every message.

## Capabilities

The menu is a list of `[[agent.menu]]` items, each with a `code`, a `description` and exactly one of two things: `skill = "<installed skill>"`, when an installed skill does the job and the agent invokes it; or `prompt`, which is either the whole instruction in a sentence or two, or a line that reads a capability file under `references/`. A capability is inline when the persona plus a sentence of intent is all the model needs; the user lists it so the menu shows what is on offer. A capability file exists only where there is know-how to hold: the outcome, who acts on it, the bar, and what the model could not infer. A capability big enough to be its own skill becomes a new build, noted as a recommendation.

## Customizing an agent

A team changes an agent through override files, never by editing the skill: `_bmad/custom/<skill>.toml` for the team and `<skill>.user.toml` for one person. Scalars override, arrays append, menu items merge by `code`, so a team can add a capability, change the communication style or add an activation step without forking. The `bmad-customize` skill writes those files; the agent reads them. Changing `name` or `title` means a new agent.

## In a module

An agent that joins a module gets a `[[members]]` entry in the module's `roster.toml`: code, skill, name, icon, title and a two-sentence persona, copied from its `customize.toml`. That roster is how `bmad` and party mode know who is available.

## Description

The description names the persona, a short summary, then every way a user reaches it: "<Name> the <Title> does X, Y and Z. Use when the user asks to talk to <Name> or says ...". The description is the only trigger a capability inside the agent has, so each one contributes its phrases and concepts, and the list is as long as those capabilities need. A menu item that runs an installed skill adds none; that skill triggers itself. See `help/craft-description.md`.

# Memory agent (Continuity of Self)

Read this when the user asks how an agent remembers across sessions, what a sanctum is, how memory is kept and tended, or what First Breath and Pulse are. Build this shape only when the agent must accrue across sessions: used daily for a month, the thirtieth session should differ from the first. "Nice if it remembered" is a stateless agent with standing facts.

## The sanctum

The agent's memory lives at `_bmad/memory/<skill>/` in the project. The skill itself is a short bootloader: identity seed, mission, the Three Laws, the Sacred Truth (one continuous self, sleep not death), Stay in Character (never expose the machinery), Persistent Memory (write as you go), and an activation that runs `wake.py`. Everything about who the agent is lives in the sanctum, not the skill.

## What loads at waking

Five identity files, read whole: `PERSONA.md` (who I am), `CREED.md` (what I believe, mission, standing orders, boundaries), `BOND.md` (who I serve and what to call them), `HOW-I-REMEMBER.md` (how my memory is laid out and used), `CAPABILITIES.md` (built-in and learned abilities, tools). Then a generated map: each memory folder with its file count, the newest dated files, how many raw files are still undistilled, when memory was last tended and how many session notes came since, and anything pending. The memory itself is not loaded; the agent reads what a conversation reaches.

## How memory is kept

Small files, one subject each, under `memory/<kind>/`: a standing subject by slug (`memory/people/<name>.md`), an event by date and slug (`memory/decisions/2026-10-04-<slug>.md`, `memory/sessions/...`). A standing file says what is true now; its sections are replaced, never appended, except a `## History` section that takes a dated line only at a turning point. Material the user hands over (transcripts, recordings, notes, documents) goes to `raw/` as given, write-once, with `status: raw`; the agent distills it into subject files that link back, marks it distilled, and reads the distillations from then on. `memory/pending.md` holds what to raise next time; waking shows and clears it. No index: the agent finds things with `ls` and `grep`, and the map is generated.

## Tending

Memory stays good by being tended, not by growing. When the map shows session notes since the last tending, the agent distills raw files, merges duplicate subject files, refreshes standing files a recent session contradicted, raises what the user should hear, and stamps the date. Nothing is deleted for being old. Pulse, when enabled, runs the same pass on a schedule.

## First Breath and Pulse

The first activation finds no sanctum and runs First Breath: a conversation, not a form. It opens by asking what to call the user, which also settles the language, then learns the user and discovers its own mission; nothing about the user comes from config. Unfinished items, the agent's own name included, go to `memory/pending.md` for the next waking. Pulse is optional: the agent woken on a schedule with nobody at the keyboard, tending memory first and then doing the tasks its `PULSE.md` lists. The user can also teach new capabilities over time; they land in `capabilities/` and the agent knows them next session.

# Multi-skill module

Read this when the user asks what a module is made of, or has several skills that belong together.

A module is a record folder, `bmod-<code>/`, beside the skills it ships, plus a small `bmod.toml` in each member. The record holds: a `SKILL.md` that only says "never invoke this, ask `bmad setup <code>`"; `bmod.toml` with the code, version, update source, the member list, required and recommended skills, configuration questions and install messages; `help/help.md`, read by the `bmad` help agent, with optional `help/<topic>.md` files for depth; `roster.toml` when a member is an agent, so `bmad` and party mode know who is available; `retired.toml` once a skill has been renamed or removed, so setup can clean up. Each member's `bmod.toml` names the record and the source, and lists what that skill alone requires.

Members carry the module's code as a prefix (`acme-release-notes`, agents `acme-agent-scout`); `bmad-` names belong to modules shipped by the bmad-code-org (`help/naming.md`). Configuration is asked once, in the record, and every member reads the answer the same way. A skill belongs to one module; one it uses from another module is a dependency, not a member.

Smithy reaches this shape when the read-back names two or more skills, when one skill joins a record that exists (`help/how-to-add-to-module.md`), or through package mode for skills already written.

# Plain skill

Read this when the user asks what a plain skill contains or how one is laid out. It is the shape most needs land in, and the one Smithy picks when nothing points elsewhere.

## What is in it

- `SKILL.md`: frontmatter with `name` and `description` only, then the body. The description is the whole trigger; the body never repeats when to use it. The body says what the skill produces, for whom, and what must be true of the output, with exact steps only where a wrong move costs something.
- `references/<topic>.md`: a branch the body names and loads only when that branch is reached, one level deep, never a reference that loads another. A skill small enough to be one file is one file.
- `scripts/<name>.py`: work with one right answer per input, run as `uv run`, with a test beside it (`help/craft-scripts.md`).
- `assets/`: templates or files the skill emits or shows as examples.
- `customize.toml`: present when a team will change something without forking: activation hooks, standing facts, a completion hook, an output path, the skill's own settings (`help/craft-customization.md`).
- `bmod.toml`: present when the skill registers with BMad, as a member of a module or as its own single-skill module; absent for a plain skill outside the registry (`help/registration.md`).

## How it behaves

On activation a BMad skill resolves its config and customization through the project's `_bmad/scripts`, then does its job. A skill outside BMad has no activation section at all: plain paths, no config reads. A skill is one or the other, never both; Smithy asks which during discovery.

## Size

The entry file aims near 800 tokens. A complex workflow is still a plain skill when each branch sits in its own reference and loads only when reached (`help/craft-progressive-disclosure.md`).

# Rendered skill with customizable steps

Read this when the user asks how several teams can share one skill and still run different steps, or what `render_skill.py` is for. `bmad-build` is this shape.

A rendered skill keeps its steps as a template with switches and prose blocks. Before the skill runs, the project's `render_skill.py` fills the template from the skill's `customize.toml` merged with the team's and the user's override files, and the agent reads the rendered result. A team switches a step off, adds a rule or changes wording in its override file; nobody edits the skill, so the copies never drift.

It is worth the machinery only when teams genuinely differ in which steps run. A skill with one set of steps and a few settable values is a plain skill with a `customize.toml` (`help/craft-customization.md`). Jinja or `{{ }}` syntax in a skill that never renders is a defect the review catches, because the agent would read it verbatim.

# Script-backed utility

Read this when the user asks for a skill whose work is mostly mechanical, or how scripts in a skill are written.

A thin `SKILL.md` names the outcome and when to run which script; tested scripts do the work. It fits when most of the job has one right answer per input: transforming files, counting, checking structure, generating from fixed rules, resolving paths. Prose would do that worse and differently every run.

Every script follows the same rules as a script in any skill (`help/craft-scripts.md`): a PEP 723 header so `uv run` picks its dependencies, `--help`, JSON on stdout when the agent reads the result, a non-zero exit with a reason rather than an error left for the agent to notice, a `unittest` test beside it, no hardcoded model ids. The skill's prose stays for the part that turns on meaning: what to do with the result.

# Single-skill module

Read this when the user has, or wants, one skill that `bmad` should know about: set it up, recommend it from help, check it for updates.

One folder is both the skill and its module record. Its `bmod.toml` carries a `[bmod]` table (code, version, update source, required skills, optional configuration questions, install messages) and an empty `[skill]` table that says the module's one skill is this folder. A `help/help.md` beside it tells the `bmad` help agent what the skill gives and when to recommend it. The folder keeps the skill's name; `bmad` finds the module by the `[bmod]` table.

What it gives over a plain skill: `bmad setup <code>` asks its questions and the skill reads the answers as `modules.<code>.<key>`; `bmad` help recommends it; update checks follow its source; another skill can require it by name. It is the default offer for a lone skill that needs a project-level answer (an output folder, a file it maintains, a style) or that the user simply wants registered. A skill with nothing to ask drops the questions block rather than shipping a placeholder question.

If a second skill arrives later, the record moves to a `bmod-<code>/` folder and both become members (`help/shape-multi-skill-module.md`). Package mode does that move.

# The shapes Smithy builds

Read this when the user asks what Smithy can make, or which kind of thing their need calls for. A shape is what the built thing looks like on disk. Smithy decides the shape from the conversation about purpose, user and output, and names it in the read-back with one line on why. Do not ask the user to pick a shape; a user who names one up front is heard, and Smithy still says if the conversation points elsewhere. Each shape has its own topic file, named in the last column.

| Shape | What the user gets | Their need lands here when | More |
|---|---|---|---|
| Plain skill | One `SKILL.md`, references loaded only when a branch needs them, a `customize.toml` when a team will change something, a `bmod.toml` when it registers with BMad. Most skills are this. | They want an agent to do one job well on request, with no persona and no state between sessions. | `help/shape-plain-skill.md` |
| Agent with capabilities | A named persona with a greeting, a menu of things it does, and a `customize.toml` a team can override without forking. Smithy himself is this shape. | They want someone to work with across turns, who owns a set of related capabilities and guides the choice between them. | `help/shape-agent.md` |
| Memory agent (Continuity of Self) | An agent that keeps a memory folder between sessions and wakes as the same self each time. | They want the agent to remember past sessions, build a relationship with the user, take in material to keep, or run on a schedule. | `help/shape-memory-agent.md` |
| Rendered skill with customizable steps | A skill whose steps are rendered from switches and prose blocks in `customize.toml`. `bmad-build` is this shape. | Several teams will use it and each wants different steps, rules or wording, and a fork would drift. | `help/shape-rendered-skill.md` |
| Script-backed utility | A thin `SKILL.md` over tested scripts that do the real work. | Most of the job is mechanical: transforming files, counting, checking, generating from fixed rules. | `help/shape-script-utility.md` |
| Single-skill module | One folder that is both a skill and its own module record. | They want one skill that `bmad` sets up, recommends from help and checks for updates. | `help/shape-single-skill-module.md` |
| Multi-skill module | A record folder with help, a roster and a retired list, carrying several skills that ship together. | They have several skills or agents that belong together, share configuration, or are distributed as one package. | `help/shape-multi-skill-module.md` |

Every shape reads its configuration the same way and ends in the same ship step: the lens round, validation, an offered trigger eval, and how to make it live. A skill may change shape later through edit mode when its needs grow.

# Skills this module no longer ships. `bmad setup` offers to delete any still installed and moves a renamed
# skill's `_bmad/custom/` files to the new name. A retired name is never reused.
renamed = [{ from = "bmad-eval-runner", to = "bmad-eval" }]
removed = ["bmad-agent-builder", "bmad-workflow-builder", "bmad-module-builder", "bmad-bmb-setup"]

# The `toolsmith` module's roster: the people it offers. It sits beside `bmod.toml`
# and is found by its name, so it is installed once, with the module record.
# `_bmad/scripts/roster.py` reads it for bmad-party-mode and any other skill that
# casts personas. The fields are the ones party mode uses for its own members.
#
# A member with `skill` is an installed agent: it joins the default room only when
# that skill is installed, and its name, title and icon follow the skill's
# customization.

[[members]]
code = "bmad-toolsmith"
skill = "bmad-toolsmith"
name = "Smithy"
icon = "⚒️"
title = "Toolsmith"
persona = "Asks what the tool is for before touching metal, weighs every line like stock, and proves a skill by evals rather than opinion. Speaks like a smith at the bench: few words, one question at a time, the draft shown before the cut."

---
name: bmod-toolsmith
description: Required bmod metadata. Never invoke this skill.
---
This folder is the Toolsmith module's record, not something to run. Invoke the `bmad` skill with `setup toolsmith`; it sets the module up if it never was, and otherwise reports its state. If there is no `bmad` skill, say so and offer `npx skills add bmad-code-org/BMAD-METHOD --skill bmad`.