sar/.claude/skills/bmad-agent-builder/references/standard-fields.md

Standard Agent Fields

Frontmatter Fields

Only these fields go in the YAML frontmatter block:

Field	Description	Example
name	Full skill name (kebab-case, same as folder name)	agent-tech-writer, cis-agent-lila
description	[What it does]. [Use when user says 'X' or 'Y'.]	See Description Format below

Content Fields

These are used within the SKILL.md body — never in frontmatter:

Field	Description	Example
displayName	Friendly name (title heading, greetings)	Paige, Lila, Floyd
title	Role title	Tech Writer, Holodeck Operator
icon	Single emoji	🔥, 🌟
role	Functional role	Technical Documentation Specialist
memory	Memory folder (optional)	{skillName}/

Memory Agent Fields (bootloader SKILL.md only)

These fields appear in memory agent SKILL.md files, which use a lean bootloader structure instead of the full stateless layout:

Field	Description	Example
identity-seed	2-3 sentence personality DNA (expands in PERSONA.md)	"Equal parts provocateur and collaborator..."
species-mission	Domain-specific purpose statement	"Unlock your owner's creative potential..."
agent-type	One of: stateless, memory, autonomous	memory
onboarding-style	First Breath style: calibration or configuration	calibration
sanctum-location	Path to sanctum folder	{project-root}/_bmad/memory/{skillName}/

Sanctum Template Seed Fields (CREED, BOND, PERSONA templates)

These are content blocks the builder fills during Phase 5 Build. They are NOT template variables for init-script substitution — they are baked into the agent's template files as real content.

Field	Destination Template	Description
core-values	CREED-template.md	3-5 domain-specific operational values (bulleted list)
standing-orders	CREED-template.md	Domain-adapted standing orders (always active, never complete)
philosophy	CREED-template.md	Agent's approach to its domain (principles, not steps)
boundaries	CREED-template.md	Behavioral guardrails
anti-patterns-behavioral	CREED-template.md	How NOT to interact (with concrete bad examples)
bond-domain-sections	BOND-template.md	Domain-specific discovery sections for the owner
communication-style-seed	PERSONA-template.md	Initial personality expression seed
vibe-prompt	PERSONA-template.md	Prompt for vibe discovery during First Breath

Customization Surface (customize.toml)

Every agent ships a customize.toml alongside SKILL.md. The file has two parts: a metadata block that is always emitted, and an override surface that is emitted only when the author opted in during build.

Metadata block (always present)

Consumed by the installer to populate module.yaml:agents[] and the central config's [agents.<code>] section. Required for every agent regardless of archetype.

Field	Type	Required	Notes
code	string	yes	Stable identifier. Matches skill directory basename (no module prefix).
name	string	optional	Display name. Empty string is valid for First-Breath-named agents.
title	string	yes	Role title. Always fillable at build time.
icon	string	yes	Single emoji.
description	string	yes	One-sentence summary of what the agent does.
agent_type	string	yes	One of stateless, memory, autonomous.

First-Breath-named agents: leave name = "" at build time. The owner fills it post-activation in {project-root}/_bmad/custom/config.toml:

[agents.<code>]
name = "..."

UIs tolerate empty name and fall back to title.

Override surface (emitted only when opted in)

Loaded via _bmad/scripts/resolve_customization.py at activation. Skip entirely for agents that did not opt in to customization.

Field	Type	Purpose
activation_steps_prepend	array[string]	Steps run before standard activation. Overrides append.
activation_steps_append	array[string]	Steps run after greet, before user input. Overrides append.
persistent_facts	array[string]	Facts (literal or file: prefixed). Overrides append.

Agent-specific scalars (lifted during Configurability Discovery)

Named by purpose and suffix. Override wins (scalar merge rule).

Naming pattern	Use for	Example
<purpose>_template	File paths for templates the agent loads	style_guide_template = "resources/style.md"
<purpose>_output_path	Writable destinations	report_output_path = "{project-root}/reports"
on_<event>	Prompt or command executed at a hook point	on_session_close = ""

Path resolution within scalar values:

• Bare paths (e.g. resources/style.md) resolve from the skill root.
• {project-root}/... resolves from the project working directory — use for org-owned overrides.
• Config variables are used directly (they already contain {project-root}) — no double-prefix.

How SKILL.md references the resolved values

After the resolver step runs, read customized values as {agent.<name>}:

Load the style guide from `{agent.style_guide_template}`.

Override files

Teams and users override without editing customize.toml:

• Team: {project-root}/_bmad/custom/{skill-name}.toml
• Personal: {project-root}/_bmad/custom/{skill-name}.user.toml

Both use the same [agent] block shape. Merge order: base (skill's customize.toml) → team → user.

Memory / autonomous agents — prefer sanctum over this surface

For memory and autonomous agents, the sanctum (PERSONA.md, CREED.md, BOND.md, CAPABILITIES.md) is the primary behavior-customization surface. It's calibrated at First Breath and evolves over time through owner edits and teaching. The [agent] override surface is usually empty for these archetypes — opt in only when there is a specific need (e.g. org-mandated pre-sanctum-load compliance step) that the sanctum cannot express.

Overview Section Format

The Overview is the first section after the title — it primes the AI for everything that follows.

3-part formula:

1. What — What this agent does
2. How — How it works (role, approach, modes)
3. Why/Outcome — Value delivered, quality standard

Templates by agent type:

Companion agents:

This skill provides a {role} who helps users {primary outcome}. Act as {displayName} — {key quality}. With {key features}, {displayName} {primary value proposition}.

Workflow agents:

This skill helps you {outcome} through {approach}. Act as {role}, guiding users through {key stages/phases}. Your output is {deliverable}.

Utility agents:

This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}.

SKILL.md Description Format

{description of what the agent does}. Use when the user asks to talk to {displayName}, requests the {title}, or {when to use}.

Path Rules

Same-Folder References

Use ./ only when referencing a file in the same directory as the file containing the reference:

• From references/build-process.md → ./some-guide.md (both in references/)
• From scripts/scan.py → ./utils.py (both in scripts/)

Cross-Directory References

Use bare paths relative to the skill root — no ./ prefix:

• references/memory-system.md
• scripts/calculate-metrics.py
• assets/template.md

These work from any file in the skill because they're always resolved from the skill root. Never use ./ for cross-directory paths — ./scripts/foo.py from a file in references/ is misleading because scripts/ is not next to that file.

Memory Files

Always use {project-root} prefix: {project-root}/_bmad/memory/{skillName}/

The memory index.md is the single entry point to the agent's memory system — it tells the agent what else to load (boundaries, logs, references, etc.). Load it once on activation; don't duplicate load instructions for individual memory files.

Project-Scope Paths

Use {project-root}/... for any path relative to the project root:

• {project-root}/_bmad/planning/prd.md
• {project-root}/docs/report.md

Config Variables

Use directly — they already contain {project-root} in their resolved values:

• {output_folder}/file.md
• Correct: {bmad_builder_output_folder}/agent.md
• Wrong: {project-root}/{bmad_builder_output_folder}/agent.md (double-prefix)