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 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.