maestro/docs/tools/renderusertemplate.md

RenderUserTemplate

Renders a template from templates/ by substituting {{var}} placeholders with caller-supplied params.

Overview

Companion to ReadUserTemplate. Instead of returning the raw body, this tool:

1. Parses the template's frontmatter params spec (same shape as scripts / browser-macros).
2. Validates caller-supplied params against the spec (type-check + defaults applied).
3. Replaces every {{name}} placeholder in the body with the resolved value.
4. Returns the rendered body (no # Template: header, no frontmatter — just the substituted text).

Placeholders not declared in frontmatter.params are left literal — so prose like use {{column}} as the key survives unchanged when no column param exists.

---

Usage

Template file templates/weekly-report.md:

---
description: Weekly status report
params:
  - name: date
    type: string
  - name: summary
    type: string
    default: "(no summary)"
---
# Status — {{date}}

{{summary}}

Call:

{ "name": "weekly-report", "params": { "date": "2026-05-11", "summary": "shipped 3 PRs" } }

Response:

# Status — 2026-05-11

shipped 3 PRs

---

Parameters

Parameter	Type	Required	Description
name	string	Yes	Template filename, with or without .md extension (max 128 chars)
params	object	No	Key-value params matching the template's frontmatter.params spec

---

Frontmatter params schema

Identical to scripts / browser-macros:

params:
  - name: identifier  # must match /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
    type: string | number | boolean
    description: optional
    default: optional  # if omitted, the param is required

Param values are coerced to string via String(value) when substituted.

---

Error cases

• name missing or invalid characters → error.
• Template file does not exist in templates/ → error.
• Frontmatter is malformed (bad YAML, bad params shape) → error.
• A required param (no default) is missing from the call → error: param X: required but not provided.
• A param has the wrong type → error: param X: expected number, got string.

Templates without any frontmatter render as pure pass-through — any {{var}} stays literal.

---

Use cases

• Weekly / monthly reports: RenderUserTemplate({ name: "weekly-report", params: { date, summary } }).
• Email canned responses with variable substitution.
• Code boilerplate with a few configurable parts (component name, props).

For more dynamic logic (conditionals, loops), open ReadUserTemplate and do the substitution inline in your output — there is no Handlebars / Liquid / etc. engine, by design.

---

Related tools

• ReadUserTemplate — returns the raw body + frontmatter. Use this when you want to inspect the template structure or do substitution yourself.
• ListUserAssets({ kind: "templates" }) — list available templates.
• RunUserScript — for executable scripts (not just text substitution).
• This tool is a META_TOOL — no need to add it to allowed_tools in piece YAML.