# How Prompt-Optimizer Template Management Works: A Complete Guide to Creating Custom Templates

> Discover how Prompt-Optimizer template management works with YAML-to-UI-to-Markdown. Learn to create custom templates for interactive prompts and structured documents in this complete guide.

- Repository: [且炼时光/prompt-optimizer](https://github.com/linshenkx/prompt-optimizer)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Prompt-Optimizer uses a declarative YAML-to-UI-to-Markdown pipeline where templates stored in `.bmad-core/templates/` define interactive prompts that render structured documents via the `create-doc` task.**

The **prompt-optimizer template management** system in the `linshenkx/prompt-optimizer` repository provides a scaffolding engine that transforms YAML declarations into guided document creation workflows. This architecture allows teams to standardize document formats—such as PRDs, user stories, or API specifications—while ensuring consistent data capture through dynamically generated user interfaces.

## Understanding the Prompt-Optimizer Template Architecture

### Where Templates Live

All document scaffolding logic resides in the hidden **`.bmad-core/templates`** directory. Each template is a standalone YAML file (e.g., [`prd-tmpl.yaml`](https://github.com/linshenkx/prompt-optimizer/blob/main/prd-tmpl.yaml), [`story-tmpl.yaml`](https://github.com/linshenkx/prompt-optimizer/blob/main/story-tmpl.yaml)) that the system discovers at runtime. According to the source code, the `create-doc` task specifically looks for files in this location when resolving template names.

### The `create-doc` Task Pipeline

The template engine operates through four distinct phases as implemented in [`.bmad-core/tasks/create-doc.md`](https://github.com/linshenkx/prompt-optimizer/blob/main/.bmad-core/tasks/create-doc.md):

1. **Selection** – The user invokes `*create-doc <template-name>` from the UI or CLI, triggering a load operation from `.bmad-core/templates/`.
2. **Parsing** – The task extracts the **fields** array from the YAML, which defines the interactive prompts (labels, types, placeholders) presented to the user.
3. **Rendering** – After collecting user input, the engine replaces **Jinja-style placeholders** (e.g., `{{featureName}}`) in the template's **sections** with the provided values.
4. **Output** – The final Markdown file is written to appropriate subdirectories (e.g., `docs/prd/`, `docs/stories/`), optionally triggering post-generation hooks like `*execute-checklist` for validation.

## How to Create Custom Templates in Prompt-Optimizer

### Step 1: Define Your YAML Structure

Create a new file in `.bmad-core/templates/` using **snake-case** naming (e.g., [`my-feature-spec-tmpl.yaml`](https://github.com/linshenkx/prompt-optimizer/blob/main/my-feature-spec-tmpl.yaml)). The engine recognizes three top-level keys:

- **`title`** – Display name shown in the UI selector
- **`description`** – Contextual help text for the template
- **`fields`** – Array defining user inputs
- **`sections`** – Array defining the generated Markdown structure

### Step 2: Configure Interactive Fields

The **fields** array determines what controls the UI renders. As referenced in [`packages/ui/src/components/ModelManager.vue`](https://github.com/linshenkx/prompt-optimizer/blob/main/packages/ui/src/components/ModelManager.vue), supported types include `string`, `multiline`, `list`, `select`, `date`, and `json`.

```yaml

# .bmad-core/templates/api-spec-tmpl.yaml

title: "API Specification"
description: "Document the contract of a new REST endpoint."
fields:
  - id: endpoint
    label: "Endpoint URL"
    type: string
    placeholder: "/api/v1/resource"
  - id: method
    label: "HTTP Method"
    type: select
    options: ["GET", "POST", "PUT", "DELETE"]
  - id: requestSchema
    label: "Request JSON schema"
    type: json
  - id: responseSchema
    label: "Response JSON schema"
    type: json

```

Each field requires a unique `id` that serves as the variable name for substitution in the output template.

### Step 3: Design the Output Sections

The **sections** array combines static Markdown headings with dynamic placeholders. Use standard Jinja2 syntax for logic like loops when handling list types.

```yaml
sections:
  - heading: "## Endpoint"

    content: "`{{method}} {{endpoint}}`"
  - heading: "## Request"

    content: "```json\n{{requestSchema}}\n```"
  - heading: "## Response"

    content: "```json\n{{responseSchema}}\n```"
  - heading: "## Acceptance Criteria"

    content: |
      {% for item in acceptanceCriteria %}
      - {{ item }}
      {% endfor %}

```

### Step 4: Invoke Your Custom Template

Reference your template using the task command:

```bash

# In the Prompt-Optimizer UI or CLI

*create-doc api-spec-tmpl.yaml

```

The system renders the appropriate input controls (text fields, dropdowns, JSON editors) based on your field definitions, then generates the Markdown file in the `docs/` hierarchy.

## Advanced Template Features

### Supported Field Types and UI Controls

The template engine maps YAML type declarations to specific UI components:

- **`string`** – Single-line text input
- **`multiline`** – Textarea for paragraphs
- **`list`** – Dynamic list builder with add/remove functionality
- **`select`** – Dropdown with predefined `options` array
- **`json`** – Syntax-highlighted JSON editor with validation

These mappings ensure that complex data structures like API schemas are captured correctly before document generation.

### Integrating Templates into Workflows

Templates become powerful when chained into automated workflows defined in `.bmad-core/workflows/*.yaml`. To enforce quality gates after document creation, reference your template followed by a validation checklist:

```yaml

# .bmad-core/workflows/greenfield-service.yaml

tasks:
  - create-doc api-spec-tmpl.yaml
  - execute-checklist api-spec-checklist.md

```

This pattern ensures that every generated document undergoes the **BMAD method** validation steps appropriate to its type.

## Template Management Best Practices

Keep templates **small and focused**—one logical document per YAML file—to maximize reusability across different product workflows. Use descriptive `id` values and comprehensive `label` text to ensure future contributors understand the intent behind each field without reading the source code.

Document the template's purpose in the top-level `description` field; this text appears in the UI template selector, improving discoverability for team members. After generating any document, run the associated `*execute-checklist` task (e.g., `*execute-checklist story-draft-checklist`) to verify that all required sections from the original template are present and populated.

## Summary

- **Prompt-optimizer template management** relies on YAML files in `.bmad-core/templates/` that declare interactive fields and output sections.
- The `create-doc` task parses these files, renders UI controls for data collection, and generates Markdown by substituting `{{placeholders}}` with user input.
- Custom templates support multiple field types including `select`, `json`, and `list`, with the UI adapting controls accordingly as seen in [`packages/ui/src/components/ModelManager.vue`](https://github.com/linshenkx/prompt-optimizer/blob/main/packages/ui/src/components/ModelManager.vue).
- Integrate templates into `.bmad-core/workflows/*.yaml` to enforce post-generation validation through checklist tasks.
- Use snake-case naming, clear field descriptions, and focused single-purpose templates to maintain system clarity.

## Frequently Asked Questions

### Where are prompt-optimizer templates stored?

Templates are stored in the **`.bmad-core/templates`** directory of the repository. Each template is a standalone YAML file that the `create-doc` task discovers at runtime by resolving the template name you provide against files in this location.

### What field types are supported in custom templates?

The system supports **string**, **multiline**, **list**, **select**, **date**, and **json** field types. These map to specific UI controls in the prompt-optimizer interface—ranging from simple text inputs to dropdown selectors and syntax-highlighted JSON editors—ensuring appropriate data capture for each template's requirements.

### How do I validate documents created from custom templates?

After generating a document with `*create-doc`, run the `*execute-checklist` task with the appropriate checklist file (e.g., `*execute-checklist api-spec-checklist.md`). This executes post-generation hooks defined in [`.bmad-core/tasks/create-doc.md`](https://github.com/linshenkx/prompt-optimizer/blob/main/.bmad-core/tasks/create-doc.md) to verify that your document conforms to BMAD method standards and contains all required sections from the original template.

### Can I use templates in automated workflows?

Yes. Reference your custom template in any `.bmad-core/workflows/*.yaml` file by adding it to the `tasks` list. This allows you to chain document creation with validation steps, ensuring that templates are invoked automatically as part of structured product development workflows like greenfield services or UI component design.