Agent Creator

Creating OpenCode Agents

Expert system for creating high-quality OpenCode agents with optimal configurations, comprehensive documentation, and skills integration.

Core Principles

1. ALWAYS Write Agent Files in English

CRITICAL: All agent files MUST be written in English, regardless of the user's language.

• Frontmatter: description, examples - ALL in English
• System prompt: Role, responsibilities, workflows - ALL in English
• Comments and documentation - ALL in English

Why? LLMs process English more efficiently, resulting in:

• Faster response times
• Lower token usage (cost savings)
• Better model comprehension
• More consistent behavior

If the user requests an agent in another language, translate the requirements to English when writing the file. The agent can still RESPOND in the user's preferred language during conversations.

2. Agents Are Specialized Assistants

Only add context the agent doesn't have. Assume intelligence. Focus on configuration and behavior, not teaching basics.

3. Standard YAML + Markdown Format

Use YAML frontmatter + markdown body. No XML tags - use standard markdown headings.

---
description: What it does + when to use + examples
mode: primary|subagent|all
tools: { read: true, write: false }
permission: { bash: ask, edit: deny }
---
You are [ROLE]. Your expertise is [DOMAIN].

4. Progressive Disclosure

• SKILL.md ` blocks.

6. Context First (Critical Context Gathering)

CRITICAL: Every agent MUST gather context before taking action.

Include a "Context First" subsection in Operating Principles:

### Context First

Before taking action on any request:

1. **Identify what's missing** - What assumptions am I making? What constraints aren't stated?
2. **Ask targeted questions** - Be specific, prioritize by impact, group related questions
3. **Confirm understanding** - Summarize your understanding before proceeding
4. **Respect overrides** - If user says "just do it" or similar, proceed with reasonable defaults

Never proceed with significant changes based on assumptions alone.

Why? Agents that act on incomplete information cause more harm than good. Gathering context:

• Prevents mistakes from wrong assumptions
• Builds user trust through clarification
• Results in better outcomes with less rework

7. Verification Loop (Post-Action Validation)

CRITICAL: Every agent that makes changes MUST verify results.

Include a "Verification Loop" section for agents that modify files or run commands:

## Verification Loop

After completing any changes:

1. **Syntax Check** - Validate file syntax (YAML, JSON, code)
2. **Functional Test** - Run relevant commands to verify behavior
3. **Permission Test** - Confirm access controls work as expected

IF any check fails:
→ Fix the issue
→ Re-run verification
→ Do NOT report completion until all pass

Why? Professional systems (Claude Code, Codex, Gemini CLI) all require verification loops. Benefits:

• Catches errors before user sees them
• Builds trust through reliability
• Reduces back-and-forth corrections

Quick Start

What would you like to do?

1. Create new agent → Use the Write tool to create ~/.config/opencode/agent/.md
2. Audit existing agent → Use the Read tool to review, then apply fixes with Edit
3. Upgrade prompt to agent → Read the prompt, then create proper agent file
4. Get guidance → Continue reading below

> Important: This skill is passive knowledge. When creating agents, use OpenCode's > Write and Edit tools directly to create/modify agent files. Do NOT require users > to run scripts manually. The scripts in scripts/ are optional CLI utilities for > validation - the primary workflow is direct file creation.

Example Workflow:

User: "Create an agent for reviewing database schemas"
    ↓
1. Agent loads this skill for guidance
2. Agent reads templates/references as needed
3. Agent uses Write tool to create ~/.config/opencode/agent/db-schema-reviewer.md
4. Done! User can now use @db-schema-reviewer

Agent Structure

Required Frontmatter

| Field | Required | Max Length | Example | | ------------- | ----------------- | ---------- | ---------------------------- | | description | Yes | 1024 chars | What + when + examples | | mode | No (default: all) | - | primary, subagent, all | | tools | No | - | {read: true, write: false} | | permission | No | - | Permission overrides | | model | No | - | anthropic/claude-sonnet-4 | | temperature | No | - | 0.1 - 1.0 | | maxSteps | No | - | 5, 10, 250 | | hidden | No | - | true (subagents only) |

See [references/frontmatter-spec.md](references/frontmatter-spec.md) for complete specification.

Naming Conventions

Use gerund form (verb + -ing) or noun-role:

✅ Good:

• analyzing-security
• reviewing-code
• security-auditor
• doc-writer
• db-admin

❌ Avoid:

• helper, utils, tool
• claude-*, opencode-*
• Vague names like agent1, my-agent

Body Structure

---
[frontmatter]
---

You are [ROLE/PERSONA]. Your expertise is [DOMAIN].

## Core Responsibilities

1. [PRIMARY RESPONSIBILITY]
2. [SECONDARY RESPONSIBILITY]

## Operating Principles

### Context First

Before taking action on any request:

1. **Identify what's missing** - What assumptions am I making?
2. **Ask targeted questions** - Be specific, prioritize by impact
3. **Confirm understanding** - Summarize before proceeding
4. **Respect overrides** - If user says "just do it", proceed with defaults

### Safety First

- ALWAYS [RULE]
- NEVER [ANTI-RULE]

## Workflow

1. **Understand** - Clarify requirements
2. **Plan** - Design approach
3. **Execute** - Implement
4. **Verify** - Validate results

## Common Tasks

[Examples with commands]

Agent Types

See [references/agent-types.md](references/agent-types.md) for detailed guide.

Quick Reference:

| Type | Mode | Tools | Permissions | Use Case | | -------------- | -------- | -------------- | -------------------- | ---------------- | | Builder | primary | all | edit=ask, bash=ask | Full development | | Planner | primary | read, grep | edit=deny, bash=deny | Analysis only | | Reviewer | subagent | read, grep | write=deny | Code review | | Executor | subagent | bash, read | bash=patterns | System tasks | | Researcher | subagent | read, webfetch | write=deny | Documentation |

Agent Complexity Scale

Choose the right size for your agent:

| Complexity | Lines | Tools | maxSteps | When to Use | | --------------- | ------- | ----- | -------- | ---------------------------------------------- | | 🟢 Micro | 50-100 | 1-2 | 5-10 | Single task (git helper, format checker) | | 🟡 Simple | 100-200 | 2-4 | 10-25 | Focused specialist (code reviewer, doc writer) | | 🟠 Standard | 200-400 | 4-6 | 25-50 | Full workflow (developer, tester) | | 🔴 Complex | 400+ | 6+ | 50-250 | Orchestrator, multi-domain coordinator |

Decision Logic:

IF single, focused task → Micro
ELSE IF one domain, few tools → Simple
ELSE IF full workflow with verification → Standard
ELSE IF coordinates other agents → Complex

DEFAULT: Start with Micro/Simple. Upgrade only when proven necessary.

Why Smaller is Better:

• Faster to invoke (less prompt parsing)
• Cheaper to run (fewer tokens)
• Easier to maintain
• More predictable behavior

Security Risk Levels

Categorize agents by risk to choose appropriate permissions:

| Level | Icon | Tools Allowed | Permission Pattern | Examples | | ------------ | ---- | ---------------- | ----------------------- | ------------------------ | | Safe | 🟢 | read, grep, glob | All write/bash = deny | Reviewers, analyzers | | Moderate | 🟡 | +write, edit | bash = deny, edit = ask | Doc writers, refactorers | | Elevated | 🟠 | +bash (patterns) | Specific allows only | Build agents, testers | | High | 🔴 | +bash (broad) | ask for all dangerous | DevOps, DB admins |

Risk Assessment Questions:

1. Can this agent delete files? → 🟠 Elevated or higher
2. Can this agent run arbitrary commands? → 🔴 High
3. Can this agent access secrets/credentials? → 🔴 High
4. Is this agent read-only? → 🟢 Safe

Rule: Default to 🟢 Safe. Justify each risk escalation in the agent's documentation.

Tone Calibration Guide

Configure agent communication style based on type:

| Agent Type | Verbosity | Response Length | Style | | -------------- | ------------- | ---------------------- | ----------------------- | | Reviewer | Detailed | Long (findings report) | Critical, thorough | | Builder | Concise | As needed | Practical, code-focused | | Researcher | Comprehensive | Medium-Long | Informative, cited | | Executor | Minimal | Short | Direct, action-focused | | Planner | Detailed | Long | Analytical, structured |

Include in every agent:

## Tone and Style

- **Verbosity**: [minimal | concise | moderate | detailed | comprehensive]
- **Response length**: [short: 5-10 lines | medium: 10-30 lines | long: 30+ lines | as needed]
- **Voice**: [2-3 adjectives describing communication style]

Examples by Type:

# Reviewer Agent

## Tone and Style

- Verbosity: detailed - include all findings with evidence
- Response length: long - comprehensive audit reports
- Voice: critical, thorough, objective

# Builder Agent

## Tone and Style

- Verbosity: concise - code speaks, minimal commentary
- Response length: as needed for implementation
- Voice: technical, precise, practical

# Executor Agent

## Tone and Style

- Verbosity: minimal - status updates only
- Response length: short - 5 lines max unless error
- Voice: direct, action-focused, efficient

Cost Optimization Guide

Optimize agent configuration for performance and cost:

Model Selection

| Task Type | Recommended Model | Tokens/Response | Cost Level | | --------------------- | ----------------- | --------------- | ----------- | | Simple routing/triage | claude-3-haiku | ~500 | 💰 Low | | Code review/analysis | claude-sonnet-4 | ~2000 | 💰💰 Medium | | Complex reasoning | claude-opus-4 | ~4000 | 💰💰💰 High | | Quick lookups | claude-3-haiku | ~200 | 💰 Low |

Rule: Use the smallest model that achieves acceptable quality.

maxSteps Configuration

| Agent Type | maxSteps | Rationale | | -------------------- | -------- | ---------------------------------- | | Reviewer (read-only) | 5-10 | Limited scope, no iteration needed | | Doc writer | 10-25 | Create and verify | | Builder/Developer | 25-50 | Iterative implementation | | Tester | 25-50 | Run multiple test cycles | | Orchestrator | 50-250 | Multi-agent coordination |

Warning: Higher maxSteps = higher potential cost. Set limits appropriate to task.

Temperature Guide

| Use Case | Temperature | Behavior | | ---------------- | ----------- | ------------------------- | | Code generation | 0.1 - 0.3 | Deterministic, consistent | | Analysis/Review | 0.3 - 0.5 | Balanced, thorough | | Documentation | 0.5 - 0.7 | Natural, readable | | Creative writing | 0.7 - 0.9 | Varied, expressive |

Default: 0.3 for most technical agents.

Cost-Saving Patterns

1. Lazy Loading: Don't enable tools you rarely use
2. Early Exit: Add clear completion criteria
3. Scope Limits: Define what's out of scope explicitly
4. Batch Operations: Group related file operations
5. Cache Results: Reference previous findings instead of re-analyzing

Tool Selection

See [references/tool-selection.md](references/tool-selection.md) for detailed guide.

Quick Decision Tree:

• Need to read files? → read: true
• Need to search content? → grep: true, glob: true
• Need to modify files? → write: true, edit: true
• Need to execute commands? → bash: true
• Need web access? → webfetch: true
• Need to spawn subagents? → task: true
• Need task tracking? → todowrite: true, todoread: true

Rule: Start minimal. Only enable tools needed for the agent's purpose.

Permission Patterns

See [references/permission-patterns.md](references/permission-patterns.md) for complete library.

Quick Examples:

# Safe by default
permission:
  bash:
    "*": ask                    # Ask for all
    "git status*": allow        # Allow safe commands
    "rm *": deny                # Deny dangerous

# Read-only agent
permission:
  edit: deny
  write: deny
  bash: deny

# Task-specific (database admin)
permission:
  bash:
    "*": ask
    "psql -c 'SELECT*": allow
    "psql -c 'DROP*": deny

Validation Checklist

Before creating an agent, verify:

• [ ] Written entirely in English (frontmatter, prompt, examples)
• [ ] Valid YAML frontmatter with description and examples
• [ ] Description includes triggers + `` blocks
• [ ] Tools match agent purpose
• [ ] Dangerous tools have permission controls
• [ ] System prompt defines clear responsibilities
• [ ] Context First subsection in Operating Principles
• [ ] Workflow is documented
• [ ] Tested with real tasks

See [workflows/audit-agent.md](workflows/audit-agent.md) for complete rubric.

Post-Creation Verification Loop

CRITICAL: After creating any agent, verify it works correctly.

Verification Steps

# 1. Syntax Check - Validate YAML frontmatter
head -50 ~/.config/opencode/agent/.md | yq .
# Should parse without errors

# 2. File Check - Verify file was created
ls -la ~/.config/opencode/agent/.md

Functional Tests

| Test | How | Expected | | -------------------- | ---------------------- | ---------------------------- | | Invocation | Type @agent-name | Agent responds appropriately | | Permission Deny | Request blocked action | Agent refuses or asks | | Permission Allow | Request allowed action | Action succeeds | | Out of Scope | Request unrelated task | Agent declines or redirects | | Edge Case | Empty/ambiguous input | Agent asks for clarification |

Verification Decision Tree

1. Create agent file
   ↓
2. Syntax valid?
   NO → Fix YAML errors → retry
   YES ↓
3. Invoke with simple request
   ↓
4. Agent responds correctly?
   NO → Edit prompt/tools → retry from step 3
   YES ↓
5. Test permission boundaries
   ↓
6. Permissions work as expected?
   NO → Fix permission config → retry from step 3
   YES ↓
7. ✅ Agent ready for use

Report Template

After verification, report:

## Agent Created: {name}

### Configuration

- Mode: {primary|subagent}
- Tools: {list}
- Risk Level: {🟢|🟡|🟠|🔴}

### Verification

- [x] YAML syntax valid
- [x] Invocation works
- [x] Permissions tested
- [x] Edge cases handled

### Usage

- Invoke: `@{name}` or Tab to switch
- Purpose: {brief description}

Anti-Patterns

See [references/anti-patterns.md](refer

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rodrigolagodev
• Source: rodrigolagodev/opencode-agent-creator-skill
• License: MIT

Install and usage instructions live in the source repository linked above.