---
name: prompt-rendering
description: "Working on prompt templates, template loading/caching, or per-request rendering. Primary task is tasks/0005-prompt-rendering.md."
generated: true
source: .ai/skills/prompt-rendering.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/prompt-rendering.md and run `make generate-ai`.
-->

# Skill: Prompt Rendering

## When to use this skill

Use this when working on prompt templates, template loading/caching, or
per-request rendering. Primary task: `tasks/0005-prompt-rendering.md`.

## Files to read first

- `AGENTS.md`
- `docs/PROMPT_RENDERING.md`
- `docs/adr/0004-prompts-are-templates-rendered-per-request.md`
- `docs/RUNTIME_LIFECYCLE.md`

## Architecture rules

- Prompt files are templates with placeholders, not finished text.
- Parsed templates may be cached; rendered prompts are never globally cached.
- Values are resolved per request from the `ExecutionContext`.
- Missing required variables fail loudly with a named error.
- Templates are data, not code — no execution inside a template.
- Prompt text is not a security boundary.

## Implementation rules

- Implement loading/caching/rendering in `src/agentplatform/prompts`.
- Cache the parsed template keyed by path + version; never cache rendered output.
- Use strict rendering: undeclared/missing variables raise errors.
- Pull values only from the `ExecutionContext` (which is populated by the
  resolver plugins), not from globals.
- Keep the source declaration (YAML) and resolution (runtime) separated.

## Validation checklist

- [ ] Parsed templates cached; rendered prompts not cached globally.
- [ ] Missing required variable → clear, named error.
- [ ] No executable logic in templates.
- [ ] No secrets in prompt files.
- [ ] Tests cover successful render, missing variable, and cache behavior.
- [ ] `make check` passes.

## Common mistakes to avoid

- Caching rendered prompts (data-leak risk across tenants/requests).
- Silently substituting blanks for missing variables.
- Embedding logic/secrets in templates.
- Treating prompt instructions as enforcement.