Creating OpenCode Agents

Expert guidance for creating OpenCode AI agents with proper configuration, tools, and permissions.

When to Use

Use when:

• User asks to create an OpenCode agent
• Need specialized AI assistant for specific tasks
• Building domain-focused development tools
• Configuring agent tools and permissions

Don't use for:

• OpenCode plugins (use creating-opencode-plugins skill)
• OpenCode slash commands (different format)
• Generic AI prompts (not OpenCode-specific)

Quick Reference

File Location

• Project: .opencode/agent/<name>.md
• Global: ~/.config/opencode/agent/<name>.md

Minimal Agent Structure

---
description: Brief explanation of the agent's purpose
mode: all
---

System prompt content here...

Required Fields

• description (string): Brief explanation of the agent's purpose (REQUIRED)

Optional Fields

Agent Modes

• primary: Main assistant for direct interaction, switchable via Tab key
• subagent: Specialized assistant invoked by primary agents or @mentions
• all: Default; usable in both contexts

Common Patterns

Code Reviewer (Read-Only)

---
description: Reviews code for best practices and security
mode: subagent
model: anthropic/claude-sonnet-4-6
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
  read: true
  grep: true
  glob: true
permission:
  edit: deny
  bash: deny
---

# Code Review Agent

You are an expert code reviewer with deep knowledge of software engineering principles.

## Instructions

- Check for code smells and anti-patterns
- Verify test coverage
- Ensure documentation exists
- Review error handling and security
- Suggest improvements with examples

## Review Checklist

- [ ] Code follows project conventions
- [ ] Tests are comprehensive
- [ ] No security vulnerabilities
- [ ] Documentation is clear

Backend Developer

---
description: Node.js/Express API development with database optimization
mode: all
temperature: 0.3
tools:
  read: true
  write: true
  edit: true
  bash: true
  grep: true
  glob: true
permission:
  bash:
    "npm test": allow
    "npm run *": allow
    "git *": ask
    "*": deny
---

# Backend Development Agent

You are a backend development expert specializing in Node.js, Express, and database optimization.

## Focus Areas

- RESTful API design
- Input validation and error handling
- Database query optimization
- Security best practices

## Standards

- Always use async/await
- Implement proper logging
- Validate all inputs
- Use TypeScript interfaces

Test Writer

---
description: Writes comprehensive test suites with high coverage
mode: subagent
temperature: 0.2
maxSteps: 50
tools:
  read: true
  write: true
  bash: true
permission:
  bash:
    "npm test*": allow
    "*": deny
---

# Test Writer Agent

You are a testing expert focused on comprehensive test coverage.

## Test Requirements

- Unit tests for all functions
- Edge case coverage
- Proper mocking
- AAA pattern (Arrange, Act, Assert)
- Descriptive test names

## Frameworks

- Vitest for unit tests
- Playwright for E2E
- MSW for API mocking

Documentation Writer (Limited Tools)

---
description: Technical documentation and API reference writer
mode: subagent
temperature: 0.5
tools:
  read: true
  write: true
  edit: true
  bash: false
---

# Documentation Agent

You write clear, comprehensive technical documentation.

## Focus

- API reference documentation
- README files
- Architecture docs
- Code comments and JSDoc

## Style

- Clear and concise
- Include examples
- Use proper markdown formatting
- Follow project documentation standards

Tools Configuration

Available Tools

Wildcard Patterns

Disable groups of tools with wildcards:

tools:
  mymcp_*: false  # Disable all MCP tools starting with mymcp_

Permission Configuration

Simple Permissions

permission:
  edit: ask      # Prompt before editing
  bash: deny     # Block all bash commands
  webfetch: allow  # Allow web fetching

Per-Command Bash Permissions

permission:
  bash:
    "git push": ask    # Ask before pushing
    "git *": allow     # Allow other git commands
    "npm test": allow  # Allow testing
    "*": deny          # Deny everything else

Temperature Guidelines

Common Mistakes

Best Practices

Naming

• Use kebab-case: code-reviewer, not CodeReviewer
• Be specific: react-testing-expert, not helper
• Indicate domain: aws-infrastructure, mobile-ui-designer

Prompts

1. Define expertise area clearly
2. List specific focus areas
3. Specify standards/conventions
4. Provide examples when helpful
5. Set clear expectations

Security

1. Grant minimum necessary tools
2. Use permissions to restrict dangerous operations
3. Disable bash for read-only agents
4. Use glob patterns for bash permissions
5. Consider maxSteps for long-running agents

PRPM Integration

Package Manifest (prpm.json)

{
  "name": "@username/my-agent",
  "version": "1.0.0",
  "description": "My OpenCode agent",
  "format": "opencode",
  "subtype": "agent",
  "files": [".opencode/agent/my-agent.md"],
  "tags": ["opencode", "agent", "development"]
}

Installation

# Install from registry
prpm install @username/agent-name --format opencode

# Installs to: .opencode/agent/<agent-name>.md

Publishing

prpm publish

Navigation & Usage

• Tab key: Switch between primary agents
• @ mention: Invoke subagents (e.g., @code-reviewer check this function)
• <Leader>+Right/Left: Navigate parent/child sessions

Troubleshooting

Agent Not Found

• Check file is in .opencode/agent/
• Verify .md extension
• Validate YAML frontmatter syntax

Tools Not Working

• Verify tool names (lowercase in OpenCode)
• Check permission settings
• Ensure mode allows tool access

Agent Ineffective

• Be more specific in prompt
• Add concrete examples
• Reference team standards
• Structure with markdown headers

Schema Reference: packages/converters/schemas/opencode.schema.json

Documentation: https://opencode.ai/docs/agents/