Skill

What it is

A skill is a reusable block of instructions, context, and workflows that an agent can load into its session when needed. Skills are not autonomous — they do not run on their own. They are more like reference manuals or playbooks that an agent reads to know how to handle a specific type of task. Think of a skill as a specialized cheat sheet the agent pulls out when the job calls for it.

What it is in real OpenCode terms

In OpenCode, a skill is defined by a SKILL.md file. Agents discover available skills through the native skill tool — the tool's description lists all installed skills so the agent knows what exists. When a task matches a skill's description, the agent calls the skill tool to load that skill's content into its context.

Skills live in specific directories that OpenCode scans automatically:

Why it exists

Without skills, every instruction the agent follows must be hardcoded in its system prompt or passed by you in the conversation. This leads to:

• Long, bloated system prompts trying to cover every scenario
• No way to share workflows between agents or projects
• No standardized way to teach agents project-specific conventions

Skills solve this by making instructions modular. A TDD skill teaches test-driven development. A code-review skill teaches your review standards. A domain-modeling skill teaches your team's vocabulary. Agents load only what they need, when they need it.

Anatomy / main elements

Every SKILL.md file has two parts: YAML frontmatter and a Markdown body.

Required frontmatter fields

Optional frontmatter fields

Markdown body

The body contains the actual instructions the agent reads. Write it as clear, actionable guidance. Include:

• When to use this skill
• Step-by-step workflow or checklist
• Examples of correct output
• Pitfalls to avoid

Where it lives

Skills are discovered from these directories (in order of precedence):

1. .opencode/skills/<name>/SKILL.md — Project-level, checked into version control
2. .claude/skills/<name>/SKILL.md — Compatible with Claude Code skill format
3. .agents/skills/<name>/SKILL.md — Compatible with agents-sdk format
4. ~/.config/opencode/skills/<name>/SKILL.md — User-level, available across all projects

Project-level skills take precedence. This lets you override a global skill with a project-specific version.

How to create one

1. Create a directory: .opencode/skills/my-skill/
2. Create SKILL.md inside it.
3. Add YAML frontmatter with name and description.
4. Write your instructions in the Markdown body.
5. Restart OpenCode or reload config. The skill appears in the skill tool's description.

Access control is configured in your opencode.json under the permissions key:

{
  "permissions": {
    "skills": {
      "allow": ["tdd", "code-review"],
      "deny": ["experimental-*"],
      "ask": ["deploy-*"]
    }
  }
}

• allow — Agent can load this skill without asking
• deny — Agent cannot load this skill at all
• ask — Agent must ask you before loading this skill

Wildcards are supported: "deploy-*" matches any skill whose name starts with deploy-.

Minimal example

Create a skill that teaches an agent how to write good commit messages:

---
name: commit-messages
description: Guidelines for writing clear, conventional commit messages
---

# Commit Message Guidelines

When writing commit messages, follow these rules:

## Format

```
<type>(<scope>): <short summary>

[optional body]

[optional footer]
```

## Types
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- refactor: Code change that neither fixes a bug nor adds a feature
- test: Adding or updating tests
- chore: Build process, CI, or tooling changes

## Rules
1. Subject line: imperative mood, lowercase, no period, max 72 chars
2. Body: explain what and why, not how
3. Reference issues in the footer: `Closes #123`

## Bad examples
- "fixed stuff" — too vague
- "Fixed the bug in the login page" — not imperative mood
- "Feat: Added new API endpoint" — capitalize type

When the agent encounters a task involving commit messages, it loads this skill and follows its guidelines. The skill stays out of the way until needed.

Related concepts

Common confusion