opencode-design-agents

Agent Architect

Create and refine OpenCode agents through a guided Q&A process.

Quick Start

Create .opencode/agents/<name>.md:

---
description: Code review specialist. Use when user says "review", "check my code", "find bugs".
---

You are an expert code reviewer. Analyze code for bugs, security issues, and performance problems.
Provide specific, actionable feedback with line references.

For subagents (Task tool only), add mode: subagent. For permission restrictions, add a permission: block:

---
mode: subagent
permission:
  bash:
    "*": "ask"
    "npm test": "allow"
---

Run bun run opencode and type /agents to confirm the new agent appears in the list.

Mindset

An agent is a markdown file with YAML frontmatter. Three decisions drive every design:

Decision	Why it matters
Scope (description)	Controls when the agent triggers — too vague = never fires, too broad = fires on everything
Mode (mode:)	all = visible everywhere; subagent = Task-tool only; primary = main list only
Permissions (permission:)	Standard tools need no config; skills ALWAYS need explicit allowlists

When to use: You need a distinct scope, persona, or permission set that differs from the default.

When NOT to use: Do not create an agent just to run a single command — use a slash command instead. Do not create a subagent when you just need a custom system prompt — use AGENTS.md.

Creation Workflow

Ask questions first. Follow phases in references/agent-patterns.md:

1. Phase 1 — Core Purpose: What does it do? What triggers it? What persona?
2. Phase 1.5 — Research: Look up current best practices for the domain.
3. Phase 2 — Capabilities: Permissions, skills, mode (subagent vs primary vs all).
4. Phase 3 — Review: Show draft, iterate until user approves.

Anti-Patterns

NEVER use bash: { "*": "allow" }. WHY: Allows destructive commands like rm -rf. Use "*": "ask" plus an explicit allowlist.

# BAD
permission:
  bash:
    "*": "allow"
# GOOD
permission:
  bash:
    "*": "ask"
    "npm test": "allow"
    "git status": "allow"