Overview
Skills are reusable instructions loaded on-demand via theskill tool. Instruction files (AGENTS.md, CLAUDE.md, CONTEXT.md) provide project-level and global AI guidance.
Skill Locations
SKILL.md Format
Frontmatter Fields
Name Validation Rules
- 1–64 characters
- Lowercase alphanumeric with single hyphen separators
- Cannot start/end with
- - No consecutive
-- - Must match directory name
- Regex:
^[a-z0-9]+(-[a-z0-9]+)*$
Skill Permissions
Control which skills agents can load:Per-Agent Skill Permissions
Disable Skills for an Agent
Instruction File Types
OpenCode discovers instruction files using a “first type wins” strategy:Discovery vs Config-Based Instructions
Discovery-based instructions (AGENTS.md, CLAUDE.md, CONTEXT.md):- Subject to profile
exclude/includepatterns (for local project files) - Follow “first type wins” rule
- Discovered by walking UP from current directory to git root
instructions array in opencode.jsonc):
- Additive to discovered files (both are loaded)
- Bypass profile
exclude/includefilters - Always loaded regardless of file type precedence
Locations
See Also
- Agents — Agent types and configuration.
- Permissions — Controlling skill access.
- Profiles Configuration — Instruction discovery with profiles.