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

Field	Type	Description
mode	primary | subagent | all	How agent can be used (default: all)
model	string	Override model (e.g., anthropic/claude-sonnet-4-20250514)
temperature	number	Response randomness 0.0-1.0
prompt	string	Path to prompt file: {file:./path/to/prompt.txt}
maxSteps	number	Maximum iterations (unlimited if unset)
tools	object	Enable/disable tools with boolean values
permission	object	Tool access: ask, allow, or deny
disable	boolean	Deactivate the agent

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-20250514
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

Tool	Description
read	Read file contents
write	Create new files
edit	Modify existing files
bash	Execute shell commands
grep	Search file contents
glob	Find files by pattern
webfetch	Fetch web content
websearch	Search the web

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

Temperature	Use Case
0.0-0.2	Code review, debugging, analysis
0.3-0.5	General development, refactoring
0.6-1.0	Documentation, brainstorming, creative work

Common Mistakes

Mistake	Problem	Fix
Missing description	Required field	Add description in frontmatter
Granting all tools	Security risk	Only grant necessary tools
Vague prompt	Ineffective agent	Be specific about domain and tasks
Wrong mode	Agent not accessible	Use all for flexibility
No tool restrictions	Agent can do anything	Use tools/permission to limit scope

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/