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

• Define expertise area clearly

• List specific focus areas

• Specify standards/conventions

• Provide examples when helpful

• Set clear expectations

Security

• Grant minimum necessary tools

• Use permissions to restrict dangerous operations

• Disable bash for read-only agents

• Use glob patterns for bash permissions

• 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 )

• +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/