OpenAgentsControl/plugins/claude-code/scripts/context/openagents-repo/standards/navigation.md

OpenAgents Repo Standards

Purpose: Standards for creating and maintaining agents in OpenAgents Control
Last Updated: 2026-01-31

---

Overview

This directory contains standards for agent creation, focusing on:

• Valid OpenCode YAML frontmatter structure
• Subagent file organization and patterns
• Common mistakes and how to avoid them

These standards emerged from fixing YAML frontmatter issues across 18 agent files.

---

Standards Files

File	Description	Priority	Lines
agent-frontmatter.md	Valid OpenCode frontmatter fields and common mistakes	critical	<200
subagent-structure.md	Standard structure for subagent files	critical	<200

---

Quick Reference

Valid OpenCode Fields (Frontmatter)

Required:

• name - Display name
• description - When to use this agent
• mode - Agent type (primary, subagent, all)

Optional:

• temperature - Response randomness (0.0-1.0)
• model - Model override
• maxSteps - Max iterations
• disable - Disable agent
• hidden - Hide from autocomplete
• prompt - Custom prompt file
• tools - Tool access config
• permission - Permission rules
• skills - Skills to load

Invalid Fields (Move to agent-metadata.json)

These fields are NOT valid in OpenCode frontmatter:

• id - Agent identifier
• category - Agent category
• type - Component type
• version - Version number
• author - Author identifier
• tags - Discovery tags
• dependencies - Component dependencies

Solution: Move these to .opencode/config/agent-metadata.json

---

Common Mistakes Fixed

1. Duplicate YAML Keys

Problem: read: true followed by read: {"**/*": "allow"}
Fix: Use only one declaration per key

2. Orphaned List Items

Problem: Lines without parent keys (e.g., - write: false)
Fix: Proper YAML structure with parent keys

3. Wrong Field Names

Problem: permission: instead of permissions:
Fix: Use correct field name permissions:

4. Extra Delimiter Blocks

Problem: Multiple --- blocks in content
Fix: Only one frontmatter block at top

5. Invalid OpenCode Fields

Problem: Fields like id, category, type in frontmatter
Fix: Move to agent-metadata.json

---

Loading Strategy

For Creating New Agents

1. Load agent-frontmatter.md - Understand valid fields
2. Load subagent-structure.md - Follow structure pattern
3. Reference existing agents as examples
4. Validate YAML syntax before committing

For Fixing Existing Agents

1. Load agent-frontmatter.md - Identify invalid fields
2. Check for common mistakes (duplicates, orphans, wrong names)
3. Move invalid fields to agent-metadata.json
4. Validate with YAML parser

For Code Reviews

1. Load agent-frontmatter.md - Check frontmatter validity
2. Load subagent-structure.md - Verify structure compliance
3. Check for common mistakes
4. Validate YAML syntax

---

Validation Commands

Check YAML Syntax

yq eval '.opencode/agent/category/agent.md' > /dev/null

Check for Duplicate Keys

grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | sort | uniq -d

List All Frontmatter Keys

grep -A 50 "^---$" .opencode/agent/category/agent.md | grep -E "^[a-z_]+:" | cut -d: -f1

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

---

Related Context

Core Concepts

• Agent Metadata System - Centralized metadata management
• Agents - Agent system overview
• Categories - Agent categorization

Guides

• Adding Agents - How to create new agents
• Testing Agents - Agent testing workflow

Lookup

• File Locations - Where files go

---

History

2026-01-31: Initial standards created after fixing YAML frontmatter issues in 18 agent files. Issues fixed:

• Duplicate YAML keys (e.g., read: true + read: {"**/*": "allow"})
• Orphaned list items (lines without parent keys)
• Wrong field names (permission: → permissions:)
• Extra --- delimiter blocks in content
• Invalid OpenCode fields in frontmatter

---

Version: 1.0.0
Maintainer: OpenAgents Control Team