74 lines
3.0 KiB
Markdown
74 lines
3.0 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, 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`.
|