Agent Templates

Templates for generating project-specific agents that understand your stack, conventions, and patterns.

What are Agent Templates?#

Agent templates are parameterized agent definitions that get customized for your specific project. Instead of using generic agents, templates generate project-specific agents that:

  • Understand your exact framework and libraries (e.g., Chi vs Gin, React vs Vue)
  • Follow your project's conventions from docs/CONVENTIONS.md
  • Know your directory structure and file organization
  • Use your database, testing, and deployment patterns

How Templates Work#

Template Structure

Templates live in ~/.config/opencode/agent-templates/ organized by category. Each template has frontmatter metadata and a parameterized agent definition.

Template Frontmatter

---
template: backend/go-chi
description: Go Chi router web service patterns
applies_to:
  frameworks: [go-chi, chi]
  language: go
generates: backend-dev.md
---

The frontmatter declares when the template applies and what agent file it generates.

Template Variables

Templates use Handlebars-style placeholders that get filled in during generation:

VariableSource
{{AGENT_NAME}}Agent file name (e.g., "Backend Dev")
{{PROJECT_NAME}}From project.json
{{PROJECT.commands.test}}Project-specific test command
{{CONVENTIONS.errorHandling}}From CONVENTIONS.md
{{#if PROJECT.database.type == 'postgres'}}Conditional sections based on project config

Template → Agent Transformation#

When a project is bootstrapped, templates matching the project's stack are rendered into project-specific agents stored in docs/agents/.

Template (generic)

# {{AGENT_NAME}}: Go Chi Agent

You are an agent for **{{PROJECT_NAME}}**.

## Commands

- Test: `{{PROJECT.commands.test || 'go test ./...'}}`
- Lint: `{{PROJECT.commands.lint || 'golangci-lint run'}}`

{{#if CONVENTIONS.errorHandling}}
## Error Handling
Follow patterns from CONVENTIONS.md.
{{else}}
## Error Handling
Use standard Go error wrapping.
{{/if}}

Generated Agent (specific)

# Backend Dev: Go Chi Agent

You are an agent for **MyApp**.

## Commands

- Test: `make test`
- Lint: `make lint`

## Error Handling
Follow patterns from CONVENTIONS.md.

The generated agent knows your project name, uses your Makefile commands, and references your conventions - no generic guessing.

When to Use Templates#

Use Templates When:

  • • Starting a new project with known stack
  • • Your framework has specific patterns
  • • You have strong conventions to enforce
  • • Multiple projects share similar stacks

Use Generic Agents When:

  • • Exploring or prototyping quickly
  • • Working with unusual/custom stacks
  • • Project is small or single-use
  • • No strong conventions needed

Available Templates (14)#

Templates are organized by category in ~/.config/opencode/agent-templates/:

Backend

Server-side implementation agents for various frameworks

Go Chi

backend/go-chi.md

Generates:

Node Express

backend/node-express.md

Generates:

Python Fastapi

backend/python-fastapi.md

Generates:

Frontend

UI implementation agents for component libraries

React

frontend/react.md

Generates:

Svelte

frontend/svelte.md

Generates:

Vue

frontend/vue.md

Generates:

Testing

Test implementation agents for different frameworks

Go Test

testing/go-test.md

Generates:

Jest React

testing/jest-react.md

Generates:

Playwright

testing/playwright.md

Generates:

Pytest

testing/pytest.md

Generates:

Critics

Code review agents for specific languages

Go

critics/go.md

Generates:

Python

critics/python.md

Generates:

Typescript

critics/typescript.md

Generates:

Styling

UI styling agents for CSS frameworks

Tailwind

styling/tailwind.md

Generates:

Creating Custom Templates#

You can create custom templates for your organization's specific patterns:

  1. 1
    Create the template file

    Add a new .md file in the appropriate category folder under agent-templates/

  2. 2
    Add frontmatter

    Define template, applies_to, and generates fields

  3. 3
    Write the agent instructions

    Use template variables to reference project-specific values

  4. 4
    Bootstrap a project to test

    Run opencode bootstrap and verify the generated agent

AutomationsChangelog