Contributing to OpenAgents Control

January 18, 2026 · View on GitHub

Thank you for your interest in contributing! This guide will help you add new components to the registry and understand the repository structure.

📚 Documentation

Development Guide - Complete guide for developing on this repo (agents, commands, tools, testing)
Agent Creation System - ⭐ NEW: Research-backed agent creation with templates
Code of Conduct - Community guidelines
Adding Evaluators - How to add new test evaluators

Repository Structure

opencode-agents/
├── .opencode/
│   ├── agent/              # Agents (category-based)
│   │   ├── core/
│   │   │   ├── openagent.md        # Universal orchestrator
│   │   │   └── opencoder.md        # Development specialist
│   │   ├── meta/
│   │   │   └── system-builder.md   # System architect
│   │   ├── development/
│   │   │   ├── frontend-specialist.md
│   │   │   └── backend-specialist.md
│   │   ├── content/
│   │   │   └── copywriter.md
│   │   └── subagents/          # Specialized subagents
│   ├── prompts/            # Prompt library (variants and experiments)
│   │   ├── core/
│   │   │   ├── openagent/
│   │   │   │   ├── gpt.md
│   │   │   │   └── llama.md
│   │   │   └── opencoder/
│   │   │       └── gpt.md
│   │   └── development/
│   │       └── frontend-specialist/
│   │           └── gpt.md
│   ├── command/            # Slash commands
│   ├── tool/               # Utility tools
│   ├── plugin/             # Integrations
│   └── context/            # Context files
├── evals/
│   ├── agents/             # Agent test suites
│   ├── framework/          # Testing framework
│   └── results/            # Test results
├── scripts/
│   ├── prompts/            # Prompt management
│   └── tests/              # Test utilities
└── docs/
    ├── agents/             # Agent documentation
    ├── contributing/       # Contribution guides
    └── guides/             # User guides

Note: Agent files now use category-based organization. Core agents are in core/, development specialists in development/, etc. When referencing agents, use the category prefix: core/openagent, development/frontend-specialist.

Key Directories

.opencode/agent/core/ - Core system agents (openagent.md, opencoder.md)
.opencode/agent/meta/ - Meta-level agents (system-builder.md)
.opencode/agent/development/ - Development specialist agents
.opencode/agent/content/ - Content creation agents
.opencode/agent/subagents/ - Specialized subagents
.opencode/prompts/ - Library of prompt variants for different models (category-based)
evals/ - Testing framework and test suites
scripts/ - Automation and utility scripts
docs/ - Documentation and guides

Quick Start

Fork the repository
Create a new branch for your feature
Add your component
Test it works
Submit a pull request

Adding New Components

Component Types

Agents (.opencode/agent/*.md) - Main AI agents
Subagents (.opencode/agent/subagents/*.md) - Specialized helpers
Commands (.opencode/command/*.md) - Slash commands
Tools (.opencode/tool/*/index.ts) - Utility tools
Plugins (.opencode/plugin/*.ts) - Integrations
Contexts (.opencode/context/**/*.md) - Context files

Component Structure

For Markdown Files (Agents, Commands, Contexts)

All markdown files should include YAML frontmatter:

---
id: devops-specialist
name: DevOps Specialist
description: "Brief description of what this does"
category: development
type: standard
version: 1.0.0
author: community
mode: primary  # For agents only
temperature: 0.1  # Optional - for agents only
tools:  # For agents only
  read: true
  edit: true
  write: true
permissions:  # Optional
  bash:
    "*": "deny"
---

# Component Name

Your component content here...

Required fields:

description - Brief description (all components)

Agent-specific fields:

mode - Agent mode (primary, secondary, etc.)
model - AI model to use
temperature - Temperature setting
tools - Available tools
permissions - Security permissions

For TypeScript Files (Tools, Plugins)

Include JSDoc comments at the top:

/**
 * Tool Name
 * 
 * Brief description of what this tool does
 */

export function myTool() {
  // Implementation
}

File Naming Conventions

kebab-case for file names: my-new-agent.md
PascalCase for TypeScript types/interfaces
camelCase for variables and functions

Adding Your Component

Create the component file in the appropriate directory:

# Example: Adding a new agent
touch .opencode/agent/my-new-agent.md

Add frontmatter and content following the structure above

Test your component:

# Validate structure
./scripts/registry/validate-component.sh

Update the registry (automatic on merge to main):

# Manual update (optional)
./scripts/registry/register-component.sh

Component Categories

When adding components, they're automatically categorized:

core - Essential components included in minimal installs
extended - Additional features for developer profile
advanced - Experimental or specialized components

The auto-registration script assigns categories based on component type and location.

Testing Your Component

Local Testing

Install locally:

# Test the installer
./install.sh --list

Validate structure:

./scripts/registry/validate-component.sh

Test with OpenCode:
```
opencode --agent your-new-agent
```

Automated Testing

When you submit a PR, GitHub Actions will:

Validate component structure
Validate prompts use defaults
Update the registry
Run validation checks

Important: PRs will fail if agents don't use their default prompts. This ensures the main branch stays stable.

Prompt Library System

OpenCode uses a model-specific prompt library to support different AI models while keeping the main branch stable.

How It Works

.opencode/
├── agent/              # Active prompts (always default in PRs)
│   ├── openagent.md
│   └── opencoder.md
└── prompts/            # Prompt library (model-specific variants)
    ├── openagent/
    │   ├── gpt.md          # GPT-4 optimized
    │   ├── gemini.md       # Gemini optimized
    │   ├── grok.md         # Grok optimized
    │   ├── llama.md        # Llama/OSS optimized
    │   ├── TEMPLATE.md     # Template for new variants
    │   ├── README.md       # Capabilities table
    │   └── results/        # Test results (all variants)
    └── opencoder/
        └── ...

**Architecture:**
- Agent files (`.opencode/agent/*.md`) = Canonical defaults
- Prompt variants (`.opencode/prompts/<agent>/<model>.md`) = Model-specific optimizations

For Contributors

Testing a Prompt Variant

# Test a specific variant
./scripts/prompts/test-prompt.sh core/openagent sonnet-4

# View results
cat .opencode/prompts/core/openagent/results/sonnet-4-results.json

Creating a New Variant

Copy the template:

cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md

Edit your variant:
- Add variant info (target model, focus, author)
- Document changes from default
- Write your prompt

Test it:

./scripts/prompts/test-prompt.sh core/openagent my-variant

Update the README:
- Add your variant to the capabilities table in .opencode/prompts/core/openagent/README.md
- Document test results
- Explain what it optimizes for
Submit PR:
- Include your variant file (e.g., my-variant.md)
- Include updated README with results
- Do NOT change the default prompt
- Do NOT change .opencode/agent/core/openagent.md

PR Requirements for Prompts

All PRs must use default prompts. CI automatically validates this.

Before submitting a PR:

# Ensure you're using defaults
./scripts/prompts/validate-pr.sh

# If validation fails, restore defaults
./scripts/prompts/use-prompt.sh core/openagent default
./scripts/prompts/use-prompt.sh core/opencoder default

Why This System?

Stability: Main branch always uses tested defaults
Experimentation: Contributors can optimize for specific models
Transparency: Test results are documented for each variant
Flexibility: Users can choose the best prompt for their model

For Maintainers

Promoting a Variant to Default

When a variant proves superior:

Verify test results:

cat .opencode/prompts/core/openagent/results/variant-results.json

Update agent file (canonical default):

cp .opencode/prompts/core/openagent/variant.md .opencode/agent/core/openagent.md

Update capabilities table in README

Commit with clear message:

git add .opencode/agent/core/openagent.md
git commit -m "feat(openagent): promote variant to default - improved X by Y%"

Note: In the new architecture, agent files are the canonical defaults. There are no default.md files in the prompts directory.

Pull Request Guidelines

PR Title Format

Use conventional commits:

feat: add new agent for X
fix: correct issue in Y command
docs: update Z documentation
chore: update dependencies
prompt: add new variant for X model

PR Description

Include:

What - What component are you adding/changing?
Why - Why is this useful?
How - How does it work?
Testing - How did you test it?

Example:

## What
Adds a new `database-agent` for managing database migrations.

## Why
Automates common database tasks and ensures migration safety.

## How
- Scans migration files
- Validates migration order
- Runs migrations with rollback support

## Testing
- [x] Validated with `./scripts/registry/validate-component.sh`
- [x] Tested with PostgreSQL and MySQL
- [x] Tested rollback scenarios

Component Dependencies

If your component depends on others, declare them in the registry:

{
  "id": "my-component",
  "dependencies": ["tool:env", "agent:task-manager"]
}

The installer will automatically install dependencies.

Registry Auto-Update

The registry is automatically updated when:

You push to main branch
Changes are made to .opencode/ directory

The GitHub Action:

Scans all components
Extracts metadata
Updates registry.json
Commits changes

You don't need to manually edit registry.json!

Code Style

Markdown

Use clear, concise language
Include examples
Add code blocks with syntax highlighting
Use proper heading hierarchy

TypeScript

Follow existing code style
Add JSDoc comments
Use TypeScript types (no any)
Export functions explicitly

Bash Scripts

Use set -e for error handling
Add comments for complex logic
Use meaningful variable names
Include help text

Quick Reference

Creating a New Agent

# Use the automated system (recommended)
/create-agent my-agent-name

# Or manually follow the development guide
# See: docs/contributing/DEVELOPMENT.md#creating-new-agents

Running Tests

cd evals/framework
npm test -- --agent=my-agent

Validating Before PR

# Validate structure
./scripts/registry/validate-component.sh

# Ensure using defaults
./scripts/prompts/validate-pr.sh

# Run tests
cd evals/framework && npm test

Common Commands

# List available components
./install.sh --list

# Validate registry
make validate-registry

# Update registry
make update-registry

# Test a prompt variant
./scripts/prompts/test-prompt.sh openagent my-variant

Questions?

Issues: Open an issue for bugs or feature requests
Discussions: Use GitHub Discussions for questions
Security: Email security issues privately
Development Help: See DEVELOPMENT.md for detailed guides

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing! 🎉