maestro/docs/tools/writeusertemplate.md

WriteUserTemplate

Creates or overwrites a Markdown template in the caller's templates/ folder.

Templates written here are immediately usable by ReadUserTemplate (to inspect them) and RenderUserTemplate (to substitute {{var}} placeholders and apply defaults).

Input

{
  name: string,        // slug — '.md' appended if absent
  content: string,     // full file text (optional frontmatter + Markdown body)
  overwrite?: boolean  // default: false — error if file exists
}

File structure

The content is plain Markdown with an optional YAML frontmatter block:

---
description: One-line description shown in ListUserAssets
params:
  - name: date
    type: string
  - name: author
    type: string
    default: "Team"
---
# Report — {{date}}

Prepared by: {{author}}

## Highlights

...

Frontmatter is not required. Templates without params: render as-is (no substitution).

Frontmatter params spec

Each param entry in params: supports:

field	required	description
name	yes	placeholder name used as {{name}} in the body
type	yes	string | number | boolean
default	no	value applied when the param is omitted

Required params (no default) must be supplied by the caller of RenderUserTemplate. Missing required params produce an error at render time.

Size limit

128 KB (UTF-8 encoded). Exceeding the limit returns isError: true.

Overwrite semantics

By default (overwrite: false) writing to an existing file is an error. Pass overwrite: true to replace the file atomically.

When to use

• You noticed a recurring structure (email skeleton, weekly report, issue template) — persist it for reuse.
• The user asks you to create or update a template so they can render it later.
• You want to encode a multi-step prompt skeleton with named slots.

Examples

Email template

WriteUserTemplate({
  name: "api-error-email",
  content: `---
description: Customer-facing API error notification email
params:
  - name: incident_id
    type: string
  - name: service
    type: string
  - name: eta
    type: string
    default: "unknown"
---
Dear Customer,

We have detected an issue with **{{service}}** (incident {{incident_id}}).

Our team is actively working on a resolution. Estimated resolution time: **{{eta}}**.

We apologize for the inconvenience.

— The Platform Team
`
})

Report skeleton (no params)

WriteUserTemplate({
  name: "weekly-retro",
  content: `# Weekly Retro

## What went well
-

## What to improve
-

## Action items
- [ ]
`
})

Error cases

Situation	isError	message contains
No authenticated user	true	"authenticated"
name missing / empty	true	"name"
name contains /, space, etc.	true	"alphanumeric"
Content exceeds 128 KB	true	"bytes"
File exists, overwrite not set	true	"overwrite"

Notes

• WriteUserTemplate is a META_TOOL — available in every movement without listing it in allowed_tools.
• After writing, use ReadUserTemplate to verify the content and RenderUserTemplate to test substitution.
• Use ListUserAssets to see all templates currently in the folder.