dotfiles/.config/opencode/skills/creating-agents/SKILL.md

name, description, permalink

name	description	permalink
creating-agents	Create or update opencode agents in this repository, including dispatch permissions and roster alignment requirements	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.