---
name: creating-agents
description: Create or update opencode agents in this repository, including dispatch permissions and roster alignment requirements
permalink: opencode-config/skills/creating-agents/skill
---

# Creating Agents

Use this skill when you need to add or revise an agent definition in this repo.

## Agents vs Skills

- **Agents** define runtime behavior and permissions in `agents/*.md`.
- **Skills** are reusable instruction modules under `skills/*/SKILL.md`.
- Do not treat agent creation as skill creation; each has different files and checks.

## Source of Truth

1. Agent definition file: `agents/<agent-name>.md`
2. Dispatch permissions for new dispatchable agents: `agents/lead.md`
   - `permission.task.<agent-name>: allow` must be present for lead dispatch.
3. Human-readable roster: `AGENTS.md`
   - Keep the roster table synchronized with actual agent files.
4. Runtime overrides: `opencode.jsonc`
   - May override/disable agent behavior.
   - Does **not** register a new agent.

## Agent File Conventions

For `agents/<agent-name>.md`:

- Use frontmatter first, then concise role instructions.
- Keep tone imperative and operational.
- Include only permissions and behavior needed for the role.
- Align with existing files such as `agents/lead.md` and `agents/coder.md`.

Typical frontmatter fields in this repo include:

- `description`
- `mode`
- `model` (for subagents where needed)
- `temperature`
- `permission`
- `permalink`

 Mirror nearby agent files instead of inventing new metadata patterns.
 Note: `agents/lead.md` is the only `mode: primary` agent. New agents should normally mirror a comparable subagent and use `mode: subagent` with an explicit `model`.

## Practical Workflow (Create or Update)

1. Inspect `agents/lead.md` and at least one similar `agents/*.md` file.
2. Create or edit `agents/<agent-name>.md` with matching local structure.
3. If the agent must be dispatchable, add `permission.task.<agent-name>: allow` in `agents/lead.md`.
4. Update `AGENTS.md` roster entry to match the new/updated agent.
5. Review `opencode.jsonc` for conflicting overrides/disable flags.

## Manual Verification Checklist (No Validation Script)

Run this checklist before claiming completion:

- [ ] `agents/<agent-name>.md` exists and frontmatter is valid/consistent with peers.
- [ ] Agent instructions clearly define role, scope, and constraints.
- [ ] `agents/lead.md` includes `permission.task.<agent-name>: allow` if dispatch is required.
- [ ] `AGENTS.md` roster row exists and matches agent name/role/model.
- [ ] `opencode.jsonc` does not unintentionally disable or override the new agent.
- [ ] Terminology stays consistent: agents in `agents/*.md`, skills in `skills/*/SKILL.md`.