| name | skill-authoring |
| description | Use when creating, editing, refactoring, or reviewing SKILL.md files and skill directories. Triggers on any edit to a SKILL.md file or skill directory (including chezmoi source forms). Do NOT use for AGENTS.md, agent definitions, or slash commands. |
Skill Authoring
Skills are on-demand procedures. AGENTS.md holds durable invariants; documentation holds reference
material; permissions and checks enforce deterministic rules.
Decide whether to create a skill
Delete content that is inferable, duplicated, obsolete, or too generic to change behavior. Create a
skill only when a recurring task needs instructions that should not load for unrelated work.
Existing data files do not prove that their authoring workflow is still active. Check current use
and deletion history before creating or restoring a skill.
Use three layers:
name and description: metadata shown in the skill tool.SKILL.md: the procedure needed whenever the skill is loaded.- Referenced files or scripts: optional detail loaded or executed only when required.
Do not move broad advice into AGENTS.md merely to shorten a skill. Keep a universal rule only when a
concrete failure justifies always loading it.
Location and frontmatter
OpenCode discovers project skills under .opencode/skills/<name>/SKILL.md and global skills under
~/.config/opencode/skills/<name>/SKILL.md. It also supports compatible .claude/skills and
.agents/skills locations.
---
name: skill-name
description: Use when creating or reviewing the artifact this skill governs.
---
name is 1-64 lowercase alphanumeric characters separated by single hyphens and matches the
directory name.description is 1-1024 characters.- OpenCode also recognizes
license, compatibility, and string-to-string metadata.
- Unknown frontmatter fields are ignored; do not invent behavioral fields.
Write the description
The description is visible before the body loads. Describe triggers and boundaries, not the
procedure itself.
- Start with
Use when as the local convention.
- Include common user phrasing, governed paths or tools, and adjacent terms when useful.
- Add a negative trigger only when a neighboring skill has an ambiguous boundary.
- Prefer a precise short description over an exhaustive keyword list.
Register the skill in always-loaded instructions only when missed loading repeatedly causes a
consequential error. Put primary-only registration in the primary prompt.
Write the body
State the purpose, required inputs, procedure, failure behavior, and verification that the agent
cannot infer elsewhere. For CLI tools, teach sequencing and non-obvious semantics; defer ordinary
syntax to --help.
- Cross-reference another skill instead of copying it.
- Keep facts needed on every invocation in SKILL.md.
- Move large, separable reference material into
references/.
- Use a script when deterministic transformation or validation is safer than prose.
- Include one example only when it communicates a contract more clearly than rules.
- Examples, including disposable checks, must obey the repository rules they are meant to teach.
The loaded skill must let the agent understand its workflow without broad preliminary discovery.
Repository discovery that is part of the workflow remains valid.
Before removing a schema, data shape, or procedure, inspect what the skill's consumers may read.
Keep the minimal canonical contract in the skill when permissions or workflow boundaries prevent
consumers from retrieving it elsewhere.
Review
- Verify frontmatter against the current OpenCode documentation.
- Confirm the name matches the directory and is unique across discovery locations.
- Remove instructions inherited from AGENTS.md or another skill.
- Confirm permitted consumers can retrieve every contract removed from the skill body.
- Check that every rule prevents a current failure and every referenced path exists.
- Delete unused references and scripts rather than preserving an empty structure.
