Instantiate a Diagram Skeleton
diagrams_templateEmit a class, sequence, or C4-context PlantUML/Mermaid skeleton or custom project template, returning validated source text to fill in and save with diagrams_create.
Instructions
Emit a built-in starter skeleton (class, sequence, or C4-context) or a custom project template in PlantUML or Mermaid, returning validated source text to fill in and then save with diagrams_create.
Built-in skeletons are pure and require no filesystem or code scan. Custom templates read one named JSON file under PROJECT_ROOT/.diagrams-templates; identical inputs and file contents yield identical source. No template evaluates code or fetches remote resources.
It never writes: nothing lands in the diagrams directory without an explicit diagrams_create call, and the emitted source clears the exact syntax gate that tool enforces, so the output can be saved as-is.
The three built-in kinds are 'class', 'sequence', and 'c4_context'. Use 'custom' with custom_template to load .json. The selected 'puml' or 'mermaid' object must contain 'source' and 'entity' strings. Source placeholders are {{title}} and {{entities}}; entity patterns support {{name}}. Reads are limited to 65536 bytes and expansion to 1000000 JavaScript string characters. Files must be regular files inside the template directory; symlinks, unknown fields, and unsupported placeholders are rejected.
Args:
template ('class' | 'sequence' | 'c4_context' | 'custom', required): Which starter skeleton to emit
custom_template (string, required only for custom): Identifier without path or extension, 1-64 letters, digits, underscores or hyphens
format ('puml' | 'mermaid', default 'puml'): Output dialect
title (string, optional, at most 200 chars): Diagram title; whitespace-only is rejected, never an empty title line
entities (string[], 1-20 items): Entity names, each an identifier matching /^[A-Za-z_][A-Za-z0-9_]*$/ at most 60 chars, no duplicates
Returns: JSON with schema: { "template": "class" | "sequence" | "c4_context" | "custom", "custom_template": string, // present only for custom templates "format": "puml" | "mermaid", "title": string | null, // the normalized one-line title, or null when none was given "source": string, // the skeleton; identical to the text block "entities": string[], // the names as accepted, in input order "entities_included": number, // length of "entities" "deterministic": true, // same inputs and template contents yield the same source "written": false // always false; save with diagrams_create }
Examples:
Use when: "Start a class diagram for the order model" -> template="class", entities=["User","Order"]
Use when: "Give me a Mermaid sequence skeleton for these services" -> template="sequence", format="mermaid", entities=["Checkout","Payment"]
Use when: "Sketch the C4 context for this system" -> template="c4_context", entities=["Web","Billing"]
Don't use when: You want generated content from code (use diagrams_generate or diagrams_generate_sequence)
Use when: "Use our team skeleton" -> template="custom", custom_template="team-model", entities=["User"]
Error Handling:
Input validation rejects unknown kinds/formats/keys, invalid custom identifiers, over-limit or whitespace-only titles, and invalid/duplicate/over-limit entity names
CustomTemplateError messages explain missing custom_template, invalid built-in/custom combinations, unreadable or invalid JSON files, unsupported dialects/placeholders, and read/expansion limits without exposing absolute paths
Emitted source passes the same syntax gate diagrams_create enforces; invalid template output returns a diagram validation error
Unexpected internal failures return a generic "Error: Unexpected internal error ..." with isError:true and are logged to stderr without source, paths, or secrets
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional diagram title, at most 200 characters. Whitespace-only is rejected rather than emitting an empty title line. Internal whitespace runs are collapsed so the title stays one line, and the normalized value is what the source and the structured output report. | |
| format | No | Output dialect for the skeleton (default: 'puml'). | puml |
| entities | Yes | Entity names to instantiate, 1 to 20 of them, each an identifier matching /^[A-Za-z_][A-Za-z0-9_]*$/ at most 60 characters long, with no duplicates. Names are emitted in the given order, one declaration each. | |
| template | Yes | Which starter skeleton to emit: 'class' (a box per entity), 'sequence' (a participant per entity), 'c4_context' (one context-level system per entity), or 'custom' (a named JSON template in the project's .diagrams-templates directory). | |
| custom_template | No | Custom template identifier without extension or path; required only when template is 'custom'. |