OpenAgentsControl/.opencode/context/openagents-repo/standards/agent-frontmatter.md

Standard: Agent YAML Frontmatter

Purpose: Valid OpenCode agent frontmatter structure and common mistakes to avoid
Priority: CRITICAL - Load this before creating or modifying agent files

---

Core Principle

Agent frontmatter must contain ONLY valid OpenCode fields. All other metadata (id, name, category, tags, dependencies) belongs in .opencode/config/agent-metadata.json.

Why: OpenCode validates frontmatter strictly. Extra fields cause validation errors.

---

Valid OpenCode Fields

Required

---
name: AgentName                      # Display name
description: "What this agent does"  # When to use
mode: subagent                       # primary, subagent, or all
---

Optional

temperature: 0.1                     # Response randomness (0.0-1.0)
model: anthropic/claude-sonnet-4     # Model override
maxSteps: 50                         # Max iterations
disable: false                       # Disable agent
hidden: false                        # Hide from autocomplete
prompt: "{file:./prompts/custom.txt}" # Custom prompt

tools:                               # Tool access
  read: true
  write: false
  edit: false
  bash: false
  task: false

permissions:                         # Permission rules
  bash:
    "git *": "allow"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"

skills:                              # Skills to load
  - task-management

---

Complete Example

---
name: TestEngineer
description: Test authoring and TDD agent
mode: subagent
temperature: 0.1
tools:
  read: true
  grep: true
  edit: true
  write: true
  bash: true
  task: true
permissions:
  bash:
    "npx vitest *": "allow"
    "pytest *": "allow"
    "sudo *": "deny"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"
---

---

Common Mistakes (Fixed in 18 Agents)

1. Duplicate Keys ❌

tools:
  read: true
  read: {"**/*": "allow"}  # ❌ Duplicate key

Fix: Use only one declaration per key

2. Orphaned List Items ❌

tools:
  read: true
  - write: false  # ❌ No parent key

Fix: Proper YAML structure (no orphaned items)

3. Wrong Field Names ❌

permission:  # ❌ Should be 'permissions'
  bash:
    "*": "deny"

Fix: Use correct field name permissions:

4. Extra Delimiter Blocks ❌

---
name: MyAgent
---
# Content
---  # ❌ Extra delimiter
More content

Fix: Only one --- block at top

5. Invalid OpenCode Fields ❌

---
id: my-agent          # ❌ Not valid
category: development # ❌ Not valid
type: agent           # ❌ Not valid
version: 1.0.0        # ❌ Not valid
tags: [coding]        # ❌ Not valid
dependencies: []      # ❌ Not valid

Fix: Move to .opencode/config/agent-metadata.json:

{
  "agents": {
    "my-agent": {
      "id": "my-agent",
      "category": "development",
      "type": "agent",
      "version": "1.0.0",
      "tags": ["coding"],
      "dependencies": []
    }
  }
}

---

Validation Checklist

• Only valid OpenCode fields?
• No duplicate keys?
• No orphaned list items?
• Correct field names (permissions not permission)?
• Only one --- delimiter at top?
• Metadata moved to agent-metadata.json?
• Valid YAML syntax?

---

Validation Commands

# Check YAML syntax
yq eval '.opencode/agent/category/agent.md' > /dev/null

# Find duplicate keys
grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | sort | uniq -d

# List all frontmatter keys
grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | cut -d: -f1

Valid keys: name, description, mode, temperature, model, maxSteps, disable, hidden, prompt, tools, permissions, skills

---

Related

• Agent Metadata: core-concepts/agent-metadata.md
• Subagent Structure: standards/subagent-structure.md
• Adding Agents: guides/adding-agent.md
• OpenCode Docs: https://opencode.ai/docs/agents/

---

Last Updated: 2026-01-31 | Version: 1.0.0