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

LocationScope
.opencode/skills/<name>/SKILL.mdProject config
~/.config/opencode/skills/<name>/SKILL.mdGlobal config
.claude/skills/<name>/SKILL.mdClaude-compatible
~/.claude/skills/<name>/SKILL.mdGlobal Claude

​
SKILL.md Format

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.

​
Frontmatter Fields

FieldRequiredDescription
nameYes1–64 chars, lowercase alphanumeric with hyphens
descriptionYes1–1024 chars, specific enough for agent selection
licenseNoLicense identifier
compatibilityNoCompatibility info
metadataNoString-to-string map for custom data

​
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: 
{
  "permission": {
    "skill": {
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}

​
Per-Agent Skill Permissions

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

​
Disable Skills for an Agent

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

​
Instruction File Types

OpenCode discovers instruction files using a “first type wins” strategy:
File TypeStatusPriorityBehavior
AGENTS.mdRecommendedPrimaryIf ANY AGENTS.md is found, ALL AGENTS.md files are used and other types are completely ignored
CLAUDE.mdFallbackSecondaryOnly used if NO AGENTS.md exists in the project tree
CONTEXT.mdDeprecatedTertiaryOnly used if neither AGENTS.md nor CLAUDE.md exist

​
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
{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

​
Locations

LocationScope
./AGENTS.mdProject-specific
~/.config/opencode/AGENTS.mdGlobal (all sessions)

​
See Also