Skip to main content

Overview

Skills are reusable instructions loaded on-demand via the skill 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/include patterns (for local project files)
  • Follow “first type wins” rule
  • Discovered by walking UP from current directory to git root
Config-based instructions (instructions array in opencode.jsonc):
  • Additive to discovered files (both are loaded)
  • Bypass profile exclude/include filters
  • Always loaded regardless of file type precedence

Locations

See Also