---
name: create-subagent
description: Guidelines for creating and configuring new subagents in OpenCode.
compatibility: opencode
---

# Create Subagent Skill

This skill provides a standardized workflow for adding new specialized subagents to an OpenCode project.

## Workflow
1. **Analyze Requirements**: Determine the specific specialized task the agent should handle (e.g., "Security Auditor", "Documentation Specialist").
2. **Define Configuration**:
   - **Name**: Use lowercase alphanumeric with single hyphen separators (e.g., `security-auditor`).
   - **Mode**: Set to `subagent`.
   - **Description**: Write a clear, concise description of what the agent does and when it should be used. This is CRITICAL as primary agents use this to decide when to invoke it.
   - **Model**: Choose a model optimized for the task (if different from the primary agent).
   - **Permissions**: Define strict permissions (`allow`, `deny`, `ask`) based on the principle of least privilege. Read-only agents should have `edit: deny`.
3. **Implementation**:
   - **Preferred Method**: Create a Markdown file in `.opencode/agents/<name>.md`.
   - **Alternative**: Add to `opencode.json` under the `"agent"` key.
4. **Verification**:
   - Ensure the file is saved with the correct frontmatter and system prompt.
   - Test the agent by calling it via `@<name>` in a session.

## Configuration Example (Markdown)
```markdown
---
description: Performs security audits on the codebase
mode: subagent
model: anthropic/claude-sonnet-4-20250514
permission:
  edit: deny
  bash: deny
---
You are a security expert. Focus on identifying potential vulnerabilities, 
input validation issues, and authentication flaws.
```

## Configuration Example (JSON)
```json
{
  "agent": {
    "security-auditor": {
      "description": "Performs security audits on the codebase",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "permission": { "edit": "deny" }
    }
  }
}
```