Brian
fc6a41c673
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site
4.8 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Make a Skill Customizable | Use customize.toml to let teams change a skill without forking it: decide what to expose, name it well, wire it into the skill, and test an override. |
|
Use a customize.toml to let a team change your skill's behavior without forking it. This page is for authors. To change a skill someone else wrote, see Customize BMad.
Every value you expose is a promise. Teams will pin values to it and commit overrides, and later releases must respect it. Expose what really varies between your users, and nothing else.
When to Use This
- Different teams need different output paths, templates, or rules
- Users would otherwise fork the skill for a small change
- Your skill should run a team's own steps before or after it works
When to Skip This
- Every user wants roughly the same value. Pick a good default.
- The skill is for you alone.
- The value is the skill's identity, not something it consumes.
- It is a memory agent. Its sanctum is already the place to shape it. See Agents with Memory.
:::note[Prerequisites]
- A skill built with Smithy, or a BMad skill of your own
bmad-customizeinstalled, to test an override :::
Steps
1. Decide What Earns a Setting
Ask three questions of each candidate. Expose it only if it passes all three.
- Does it really vary across your users?
- Is it something the skill consumes, such as a template, a fact, or an output path, and not part of what the skill is?
- Would hiding it force a fork? If one sentence in
persistent_factswould do, leave it out.
2. Ask Smithy to Add It
Tell Smithy during discovery what teams will change, or use edit mode on a skill you already have. Smithy writes the customize.toml and connects each value to the skill.
A skill uses a [workflow] table and an agent uses [agent]. Do not mix them. Persona fields in [workflow] suggest the skill should be an agent.
| Key | Use it for |
|---|---|
activation_steps_prepend, activation_steps_append |
Steps a team runs before or after activation |
persistent_facts |
Standing facts or file: globs to load for the run |
on_complete |
A hook to run when the skill finishes |
<purpose>_output_path |
Where an output lands |
run_folder_pattern |
How run folders are named |
| Your own settings | Anything else a team must vary, such as a template path |
3. Name Each Setting Clearly
Most users change settings through a conversation with bmad-customize, so names should read well aloud. release_notes_template works, and tmpl_override does not. Comment each one with when to override it.
[workflow]
# Override to send the notes to your team's release folder.
release_notes_output_path = "{project-root}/docs/releases"
# Override to use your own template.
release_notes_template = "assets/release-notes-template.md"
4. Set Defaults That Work
The skill must work with no override. Avoid boolean toggles, because a switch usually means the author never decided. Offer a value the skill consumes.
5. Read Every Value in the Skill
The skill resolves its table on activation, then reads each value as {workflow.<key>} or {agent.<key>}.
uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
A value that is declared but hardcoded in the body is a defect, because every override of it does nothing. Smithy's review flags this.
A skill never writes its own overrides, never merges TOML itself, and never carries a second code path for when BMad is absent. resolve_customization.py reads, and bmad-customize writes. Where users will change a value, the skill says so in one line: invoke bmad-customize, naming the key.
6. Test an Override
Run bmad-customize and change one value. It writes _bmad/custom/<skill>.toml for a team or _bmad/custom/<skill>.user.toml for one person. Run the skill and confirm the change took effect. Check what resolved shows the merged values.
What You Get
- A
customize.tomlbesideSKILL.md, holding your defaults and comments - Overrides that survive updates, because they live in the project and not in the skill
- Layers that merge when the skill activates: scalars override, arrays append, and arrays of tables merge by
codeorid
Tips
- Give each item in an array of tables a
codeor anid, or the resolver can only append it. - Keep project-wide values, such as the output folder, in core config. Read them with
resolve_config.py. - For an agent,
nameandtitleare fixed. A team that wants a new name or title creates a new agent. - When teams differ in which steps run, a rendered skill may fit better.