67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
---
|
|
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`.
|