ping-mee-self-service-platform/.agents/skills/bmad-toolsmith/shapes/rendered-skill/shape.md

Shape: rendered skill

A skill whose Markdown is rendered once per run from customize.toml and the team's overrides, so a team swaps a step, a rule or a route without forking. The conversation has reached it when teams must change what the skill does (not only add facts), when a selector chooses between routes, or when the body is long enough to split into steps loaded one at a time. The model is bmad-build: a SKILL.md that only renders, a workflow.md that activates and hands to step 1, numbered steps.

Files

File	From
SKILL.md	assets/SKILL-template.md
workflow.md	assets/workflow.md
step-NN-<name>.md, one per step	assets/step.md
customize.toml	assets/customize-template.toml

Rules

• SKILL.md does one thing: runs uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}", maps the words of the invocation to --set workflow.<key>=<value>, follows the printed workflow.md, and halts on any failure. No Jinja in it; the renderer excludes it.
• Jinja ({{ workflow.key }}, {% if %}, rendered("step-02-<name>.md")) lives only in workflow.md and the steps. An agent-facing {{placeholder}} sits inside {% raw %}...{% endraw %}; a single-brace {placeholder} passes through untouched. The skill's documents go under {{ initiative_folder }}, the output folder extended by the active initiative when one is set. A customization value the templates cannot act on, such as a misspelled selector, is rejected at the top of workflow.md with {{ halt("...") }}, one guard per selector.
• customize.toml holds [workflow] with activation_steps_prepend, activation_steps_append and persistent_facts. A selector is a scalar with its allowed values in the comment above it; an instruction a team may replace whole is a """ block scalar. Teams override in {project-root}/_bmad/custom/<name>.toml or <name>.user.toml; a single run overrides with --set.
• Each step is loaded when reached, says at the top what it produces, and ends by naming the next step as {{ rendered("step-NN-<name>.md") }} or by saying the workflow is complete. A step that shows a menu halts and waits for the user. No file whose name contains template carries {{ config.* }} or {{ workflow.* }}.