writing-agents（写作 Agent）

Writing Agents

Overview

Agents are specialized AI assistants with custom prompts, models, and tool access. Configure via markdown files or JSON.

When to Use

• Creating a new agent for specific tasks
• Editing agent prompts, permissions, or tool access
• Choosing between primary vs subagent mode
• Setting up task permissions for orchestration
• Reviewing agent configuration quality

Don't use for: skill files (use writing-skills), system prompts without agent context, or MCP server config.

File Locations

~/.config/opencode/agent/<name>.md     # Global agents
.opencode/agent/<name>.md              # Project-local agents
opencode.json → agent.<name>           # JSON config (either location)

Filename becomes agent name (e.g., review.md → review agent).

Frontmatter Reference

Mode Selection

Tool Configuration

tools:
  write: false # Disable write tool
  edit: false # Disable edit tool
  bash: false # Disable bash tool
  mymcp_*: false # Wildcards for MCP tools

Permission Configuration

permission:
  edit: deny # deny | ask | allow
  bash:
    "*": ask # Default for all commands
    "git status": allow # Specific command override
    "git push*": ask # Glob patterns supported
  webfetch: deny
  task:
    "*": deny # Block all subagent invocation
    "my-helper-*": allow # Allow specific subagents

Rule evaluation: Last matching rule wins. Put * first, specifics after.

Markdown Template

---
description: <what it does and when to use>
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
permission:
  edit: deny
---

<system prompt content>

Focus on:

- Point 1
- Point 2

JSON Template

{
  "agent": {
    "my-agent": {
      "description": "What it does",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/my-agent.txt}",
      "tools": {
        "write": false,
        "edit": false
      },
      "permission": {
        "bash": {
          "*": "ask",
          "git diff": "allow"
        }
      }
    }
  }
}

Common Patterns

Read-Only Reviewer

tools:
  write: false
  edit: false
  bash: false

Restricted Bash Access

permission:
  bash:
    "*": ask
    "git status": allow
    "git log*": allow
    "git diff*": allow

Orchestrator with Task Limits

permission:
  task:
    "*": deny
    "my-workers-*": allow

Common Mistakes

Validation Checklist

• [ ] Description clearly states purpose and trigger conditions
• [ ] Mode matches intended usage (primary vs subagent)
• [ ] Tools restricted appropriately for the role
• [ ] Permissions use correct ask/allow/deny values
• [ ] Bash permission rules ordered correctly (* first)
• [ ] Prompt focuses on role, constraints, and focus areas