134 lines
3.2 KiB
Markdown
134 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```ts
|
|
{
|
|
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:
|
|
|
|
```markdown
|
|
---
|
|
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
|
|
|
|
```js
|
|
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)
|
|
|
|
```js
|
|
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.
|