OpenCode Skills

In OpenCode,Agent Skillsis a mechanism for encapsulating reusable behaviors, throughSKILL.mddefined in files, enabling LLMs toload on demand and execute on demandspecific capabilities.

Compared to ordinary prompts, skills are closer to modular capability units and can be reused across multiple projects or teams.

Skills are OpenCode'scapability plugin system, which upgrades AI behavior from one-off prompts to reusable capability modules, making development workflows more standardized, composable, and applicable to complex engineering systems.

Skills exist as Markdown files. They do not execute functionality; instead, through on-demand, progressive loading, they achieve efficient and reusable knowledge transfer.

The biggest difference between Skills and traditional prompts is: on-demand loading + progressive disclosure (only when needed is the thick SOP stuffed into the context, greatly saving tokens).

Core Mechanism

Skills use the built-inskilltool for management; the workflow is as follows:

1. Scan local and global skill directories
2. Expose the available skills list in the context
3. The agent automatically selects skills based on the task
4. Load SKILL.md content on demand

This mechanism avoids loading all rules at once, improving performance and context utilization.

Core Structure of a Skill

The core of Skills is:A folder + a SKILL.md file。

The SKILL.md file contains:

• Metadata (at least a name and description)
• Instructions that tell the AI how to complete a specific task

A Skill is essentially a Markdown file (the filename is fixed as SKILL.md)

my-skill/
└── SKILL.md   （唯一必需）

SKILL.md Basic Template:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：

- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容  
- 扫描版 PDF 需配合 OCR 工具  

## 填写表单
- 读取 PDF 表单字段  
- 按输入数据填充并生成新文件  

Minimal Required Example:

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

Example with Optional Fields:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

If you need reference materials, reference examples, or execution scripts, you can use a more complex Skill directory structure:

my-skill/
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

How Skills Work

Skills use progressive loading to efficiently manage context:

• Discovery:At startup, the AI only loads each skill's name and description, keeping only the most basic identification information.
• Activation:When a task matches a skill's description, the AI reads the full SKILL.md instructions into the context.
• Execution:The AI executes according to the instructions, loading reference files or running code as needed.

This design keeps the AI fast while allowing it to obtain more information on demand.

File Placement Locations

Each skill requires its own folder, and inside the folder you place theSKILL.mdfile (note: the filename must be all uppercase). OpenCode automatically searches the following six locations:

A typical project directory structure is as follows:

your-repo/
├── .opencode/
│   └── skills/
│       ├── git-release/
│       │   └── SKILL.md      ← 发版流程技能
│       ├── code-review/
│       │   └── SKILL.md      ← 代码审查技能
│       └── api-doc/
│           └── SKILL.md      ← API 文档编写技能
├── src/
└── package.json

Discovery Mechanism

OpenCode's skill discovery is divided into two levels:

• Project-local skills:OpenCode starts from the current working directory,traverses the directory tree upward level by level, until it reaches the root of the Git working tree. In this process, it collects from each directory level along the way.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.mdall matching skill files.

• Global skills:At the same time, from~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.mdload all defined global skills.

Skills from both levels are merged and provided to the agent. If a project-local skill has the same name as a global skill,project-local skills take precedence。

Writing SKILL.md

1. Frontmatter Fields

EachSKILL.mdfile must start with YAML frontmatter (i.e.,---the wrapped part). OpenCode only recognizes the following fields; unknown fields are automatically ignored:

2. Naming Rules

nameThe field's value must satisfy all of the following conditions simultaneously; otherwise the skill cannot be loaded:

• Length is1–64 characters
• Can only containlowercase lettersandnumbers, words can use a single hyphen (-) as a separator.
• Must not-start or end with
• Must not contain consecutive--
• Must match the containingSKILL.mdoffolder name exactly.

Equivalent regular expression:

^[a-z0-9]+(-[a-z0-9]+)*$

Valid naming examples:git-release、api-doc、code-review、deploy2prod

Invalid naming examples:Git-Release(contains uppercase),-release(with-at the beginning),git--release(Continuous--）

3. Writing the Description

descriptionThe content of the field directly affects whether the agent can correctly select and call the skill.It is recommended that the description be specific and clear, explaining what the skill does and in which scenarios it is used, avoiding overly general descriptions:

• ❌ Too general:Help complete the release task.
• ✅ Specific and clear:从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4. Complete Example

Create in the project.opencode/skills/git-release/SKILL.md, with the following content:

In the Frontmatter, thenamevalue must be consistent with the folder name. In this example, the folder name isgit-release, sonameit must also be written asgit-release, otherwise the skill cannot be recognized.

How Agents Discover and Load Skills

After OpenCode starts, it injects all currently available skills in XML format into theskilltool description. Agents can learn which skills are available by viewing the tool description:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>Perform structured code reviews with consistent criteria</description>
  </skill>
</available_skills>

When the agent determines that a skill is relevant to the current task, it proactively calls theskilltool to load the completeSKILL.mdcontent:

skill({ name: "git-release" })

After loading, the instructions and context information defined in the skill enter the agent's working memory, thereby affecting subsequent behavior and output. The skill itself does not automatically execute any operations; it only provides additional context and behavioral rules for the agent.

Configuring Skill Permissions

Inopencode.jsonIn, usepermission.skillThe field controls which skills the agent can access, and supports two matching methods: exact names and Glob wildcards:

The specific effects of the three permission actions on skills are as follows:

Overriding Permissions per Agent

Different agents may need to access different skill sets. You can configure permissions separately for each agent, overriding the global defaults.

1. Configure in the Custom Agent's Frontmatter

# 文件路径：~/.config/opencode/agents/my-agent.md
---
permission:
  skill:
    "documents-*": "allow"    # 该代理可以加载所有 documents- 开头的技能
                               # 其他技能遵循全局权限配置
---
 
You are a documentation assistant.

2. Configure for Built-in Agents in opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {                          // 内置代理名称
      "permission": {
        "skill": {
          "internal-*": "allow"        // plan 代理可以加载 internal- 开头的技能，
                                       // 即使全局配置中对其设置了 deny
        }
      }
    }
  }
}

Disabling the Skill Tool

For agents that do not need to use skills at all, you can directly disable theskilltool. After disabling it,<available_skills>the list will be completely removed from the agent's context, saving Token consumption and preventing the agent from attempting to load any skills.

1. Disable in the Custom Agent's Frontmatter

2. Disable for Built-in Agents in opencode.json

Troubleshooting Skill Loading Issues

If a skill does not appear in the available list, check the following items in order:

1. Confirm the filename case

   SKILL.mdThe filename must be in all uppercase; if written asskill.mdorSkill.mdit will not be recognized.

2. Check Frontmatter completeness

   EnsureSKILL.mdit begins with correct YAML frontmatter and contains thenameanddescriptiontwo required fields. If either one is missing, the skill will not be loaded.

3. Confirm that the skill name is unique and correctly formatted

   If skills with the same name exist in different paths, conflicts may occur. Also checknamewhether the field conforms to the naming rules (only lowercase letters and numbers, separated by hyphens) and is exactly consistent with the folder name.

4. Check permission configuration

   Inopencode.jsonofpermission.skillIn, if the permission is"deny"The skill will be completely hidden from the agent and will not appear in the<available_skills>list. Check whether any wildcard rules (such as"*": "deny") accidentally match this skill.

For more Skills, you can refer to:

• Skills tutorial:https://www.example.com/ai-agent/skills-agent.html