prompt-rendering

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

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.