Skills › BMAD Method › bmod-toolsmith › shape-agent.md

shape-agent.md

23 lines · skills/bmod-toolsmith/help/shape-agent.md at bd70c64

Names a skill

Most marks come from matching words in the file, so treat them as pointers.

1# Agent with capabilities

3Read 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.

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.

Raw lines 1 to 4

5## Identity

7An 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.

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.

Raw lines 5 to 8

9## Capabilities

11The 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.

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.

Raw lines 9 to 12

13## Customizing an agent

15A 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.

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.

Raw lines 13 to 16

Names a skill bmad-customize :15

17## In a module

19An 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.

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.

Raw lines 17 to 20

Names a skill bmad-party-mode :19

21## Description

23The 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`.

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.

Raw lines 21 to 23