5.3 KiB
Standard Workflow/Skill Fields
Common Fields (All Types)
| Field | Description | Example |
|---|---|---|
name |
Full skill name (kebab-case) | bmad-workflow-builder, bmad-validate-json |
skillName |
Functional name (kebab-case) | workflow-builder, validate-json |
description |
[5-8 word summary]. [Use when user says 'X' or 'Y'.] | "Builds workflows through conversational discovery. Use when the user requests to 'build a workflow' or 'modify a workflow'." |
role-guidance |
Brief expertise primer | "Act as a senior DevOps engineer" |
module-code |
Module code (if module-based) | bmb, cis |
Simple Utility Fields
| Field | Description | Example |
|---|---|---|
input-format |
What it accepts | JSON file path, stdin text |
output-format |
What it returns | Validated JSON, error report |
standalone |
Opts out of bmad-init? | true/false |
composability |
How other skills use it | "Called by quality scanners for validation" |
Simple Workflow Fields
| Field | Description | Example |
|---|---|---|
steps |
Numbered inline steps | "1. Load config 2. Read input 3. Process" |
tools-used |
CLIs/tools/scripts | gh, jq, python scripts |
output |
What it produces | PR, report, file |
Complex Workflow Fields
| Field | Description | Example |
|---|---|---|
stages |
Named numbered stages | "01-discover, 02-plan, 03-build" |
progression-conditions |
When stages complete | "User approves outline" |
headless-mode |
Supports autonomous? | true/false |
config-variables |
Beyond core vars | planning_artifacts, output_folder |
output-artifacts |
What it creates (output-location) | "PRD document", "agent skill" |
Overview Section Format
The Overview is the first section after the title — it primes the AI for everything that follows.
3-part formula:
- What — What this workflow/skill does
- How — How it works (approach, key stages)
- Why/Outcome — Value delivered, quality standard
Templates by skill type:
Complex Workflow:
This skill helps you {outcome} through {approach}. Act as {role-guidance}, guiding users through {key stages}. Your output is {deliverable}.
Simple Workflow:
This skill {what it does} by {approach}. Act as {role-guidance}. Use when {trigger conditions}. Produces {output}.
Simple Utility:
This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}.
SKILL.md Description Format
The frontmatter description is the PRIMARY trigger mechanism — it determines when the AI invokes this skill. Most BMad skills are explicitly invoked by name (/skill-name or direct request), so descriptions should be conservative to prevent accidental triggering.
Format: Two parts, one sentence each:
[What it does in 5-8 words]. [Use when user says 'specific phrase' or 'specific phrase'.]
The trigger clause uses one of these patterns depending on the skill's activation style:
- Explicit invocation (default):
Use when the user requests to 'create a PRD' or 'edit an existing PRD'.— Quotes around specific phrases the user would actually say. Conservative — won't fire on casual mentions. - Organic/reactive:
Trigger when code imports anthropic SDK, or user asks to use Claude API.— For lightweight skills that should activate on contextual signals, not explicit requests.
Examples:
Good (explicit): Builds workflows and skills through conversational discovery. Use when the user requests to 'build a workflow', 'modify a workflow', or 'quality check workflow'.
Good (organic): Initializes BMad project configuration. Trigger when any skill needs module-specific configuration values, or when setting up a new BMad project.
Bad: Helps with PRDs and product requirements. — Too vague, would trigger on any mention of PRD even in passing conversation.
Bad: Use on any mention of workflows, building, or creating things. — Over-broad, would hijack unrelated conversations.
Default to explicit invocation unless the user specifically describes organic/reactive activation during discovery.
Role Guidance Format
Every generated workflow SKILL.md includes a brief role statement in the Overview or as a standalone line:
Act as {role-guidance}. {brief expertise/approach description}.
This provides quick prompt priming for expertise and tone. Workflows may also use full Identity/Communication Style/Principles sections when personality serves the workflow's purpose.
Path Rules
Only use {project-root} for _bmad paths.
Skill-Internal Files
Use bare relative paths (no prefix):
references/reference.md01-discover.mdscripts/validate.py
Project _bmad Paths
Use {project-root}/_bmad/...:
{project-root}/_bmad/planning/prd.md{project-root}/_bmad/_memory/{skillName}-sidecar/
Config Variables
Use directly — they already contain {project-root} in their resolved values:
{output_folder}/file.md{planning_artifacts}/prd.md
Never:
{project-root}/{output_folder}/file.md(WRONG — double-prefix, config var already has path)_bmad/planning/prd.md(WRONG — bare_bmadmust have{project-root}prefix)