Skip to content

Build Your First Skill

In this tutorial you build a skill with Smithy, set it up with BMad, and try it on a real request. You then add a second skill, which turns it into a module. The example makes release notes from merged pull requests, but any job you repeat will work.

  • How to give Smithy what it needs to build a skill
  • How to read and change the execution plan
  • What a single-skill module is, and why it is the default
  • How to try a skill and test that it fires
  • How one skill grows into a module

Your skill registers with BMad as a module, so bmad can set it up, recommend it, and check it for updates. One skill does not need a separate module folder. Its own folder holds everything:

FileWhat it is for
SKILL.mdThe description that triggers the skill, and the instructions the agent follows
bmod.tomlThe record that tells bmad about the skill
help/help.mdWhat the bmad skill tells users about the skill

Start bmad-toolsmith and describe the job in your own words. Include anything you already know.

Build a skill that turns the pull requests merged since the last tag into release notes for our customers.

If you have thought it through, say so and Smithy moves straight to confirming what you gave it. If the idea is thin, Smithy pushes back on it before building anything.

Smithy asks only for what your request left out, each question with the answer it would guess, so you can often just confirm. It needs to know:

  • What the skill gets done, for whom, and who uses the output
  • What must be true of the output for that person to act on it
  • The phrases you would type to reach the skill, and nearby requests it should ignore
  • Where the know-how lives, such as a runbook, an incident, or your own head
  • Whether the output can be checked
  • Whether this skill stands alone or more are planned

The question about other skills matters. When more skills are planned, Smithy settles a module code and prefix now, so nothing needs renaming later. If you describe several skills at once, Smithy plans the whole module first. See Modules and Registration.

Smithy shows what it will build and waits. Read every line, because this is the cheapest moment to change your mind.

Use a prefix of your own, not bmad-, which marks skills that BMad ships. A prefix also keeps your skills together in listings.

After you approve, Smithy writes the skill and shows you the draft and description before going further. When you have a real input, Smithy runs the skill on it once and reads how the run went, then fixes what the run shows.

Five review lenses then read every file. Smithy fixes the defects they find, cuts what a capable model would do unasked, validates the skill, and tells you what changed. Before Smithy applies a finding that changes what the skill does or how it sounds, it shows you the list and asks.

Ask the bmad skill to run bmad setup acme. Setup registers the module, creates its folder under _bmad/, and asks any configuration questions the skill has.

Start a fresh session so your tool loads the new skill, then make a real request with one of your trigger phrases:

Write the release notes for everything since v1.4.0.

Check that the skill loaded, and judge the output as the person who will use it. To change something, ask Smithy to edit the skill.

Smithy offers a trigger eval at the end of a build. Take it for any skill you expect to fire without being named. Smithy writes queries that should fire the skill and near misses that should not, and bmad-eval runs them through your tool. See Eval Runner.

When a second skill belongs with the first, ask Smithy to build it into the module:

Build acme-release-check for the acme module. It checks that a release branch is ready to tag.

The execution plan shows the registration as a member of the module. A single-skill module has no record folder yet, so Smithy moves the record into a new bmod-acme folder first. The configuration answers people already gave keep working, because the module code stays the same.

You built a skill and registered it with BMad, then grew it into a module that bmad can set up, recommend, and update.

skills-folder/
├── bmod-acme/ # the module record
│ ├── SKILL.md # says only to run bmad setup acme
│ ├── bmod.toml # code, version, source, members, questions
│ └── help/
│ └── help.md # what bmad tells users about the module
├── acme-release-notes/
│ ├── SKILL.md
│ └── bmod.toml # names the record
└── acme-release-check/
├── SKILL.md
└── bmod.toml
You want toAsk
Build a skillSmithy, “build a skill that…”
Change a skillSmithy, “change this skill to…”
Check it firesSmithy, “run a trigger eval on this skill”
Package finished skillsSmithy, “package these as a module”
Set up a modulebmad, “bmad setup ”

No. Tell Smithy you want no record and you get a plain skill. It works the same, but bmad does not recommend it, set it up, or check it for updates.

Smithy builds a plain skill. You can add a record later through convert mode.

Yes. Use the scaffold approach. Smithy lays out the files and leaves the writing to you.

No. A job you do once needs no skill. A skill earns its place when it saves you retyping a format, a preference, or a convention, or when it holds know-how the model does not have.

  • Ask the bmad skill. It reads Toolsmith’s help files and can point you to the right mode.
  • Ask in the BMad Discord.
  • Open an issue for a bug.