---
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, checks, and ownership.

## Source of Truth

1. Agent definition file: `agents/<agent-name>.md`
2. Operating roster and workflow contract: `AGENTS.md`
3. Runtime overrides and provider policy: `opencode.jsonc`
4. Workflow entrypoints: `commands/*.md`

Notes:

- This repo uses two primary agents: `planner` and `builder`.
- Dispatch permissions live in the primary agent that owns the subagent, not in a central dispatcher.
- `planner` may dispatch only `researcher`, `explorer`, and `reviewer`.
- `builder` may dispatch only `coder`, `tester`, `reviewer`, and `librarian`.

## Agent File Conventions

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

- Use frontmatter first, then concise role instructions.
- Keep tone imperative and operational.
- Define an explicit `model` for every agent and keep it on a GitHub Copilot model.
- Use only explicit `allow` or `deny` permissions; do not use `ask`.
- Include only the tools and permissions needed for the role.
- Keep instructions aligned with the planner -> builder contract in `AGENTS.md`.

Typical frontmatter fields in this repo include:

- `description`
- `mode`
- `model`
- `temperature`
- `steps`
- `tools`
- `permission`
- `permalink`

Mirror nearby agent files instead of inventing new metadata patterns.

## Practical Workflow (Create or Update)

1. Inspect the relevant primary agent file and at least one comparable peer in `agents/*.md`.
2. Create or edit `agents/<agent-name>.md` with matching local structure.
3. If the agent is a subagent, update the owning primary agent's `permission.task` allowlist.
4. Update `AGENTS.md` so the roster, responsibilities, and workflow rules stay synchronized.
5. Review `commands/*.md` if the new agent changes how `/init`, `/plan`, `/build`, or `/continue` should behave.
6. Review `opencode.jsonc` for conflicting overrides, disable flags, or provider drift.

## Manual Verification Checklist (No Validation Script)

Run this checklist before claiming completion:

- [ ] `agents/<agent-name>.md` exists and frontmatter is valid and consistent with peers.
- [ ] Agent instructions clearly define role, scope, escalation rules, and constraints.
- [ ] The owning primary agent includes the correct `permission.task` rule for the subagent.
- [ ] `AGENTS.md` roster row exists and matches the agent name, role, and model.
- [ ] `commands/*.md` and `opencode.jsonc` still reflect the intended workflow.
- [ ] Terminology stays consistent: agents in `agents/*.md`, skills in `skills/*/SKILL.md`.