OpenCode Skills

OpenCode では、エージェントスキル（Skills）は再利用可能な振る舞いをカプセル化するためのメカニズムであり、SKILL.mdファイル定義により、LLM がオンデマンドでのロード・実行を可能にし、特定の能力を実現します。

通常のプロンプトと比較すると、スキルはモジュール化された能力ユニットに近く、複数のプロジェクトやチームで再利用できます。

Skills は OpenCode の能力プラグインシステムですこれは AI の振る舞いを単発のプロンプトから再利用可能な能力モジュールへと昇格させ、開発プロセスをより標準化・構成可能にし、複雑なエンジニアリングシステムに適用できるようにします。

Skills は Markdown ファイルとして存在し、機能を実行するのではなく、オンデマンド・段階的なロードによって、効率的で再利用可能な経験の伝達を実現します。

Skills と従来の Prompt の最大の違いは、オンデマンドロード + 段階的な開示（必要なときだけ分厚い SOP をコンテキストに投入し、トークンを大幅に節約する）です。

コアメカニズム

Skills は組み込みのskillツールによって管理され、ワークフローは次のとおりです：

1. ローカルおよびグローバルのスキルディレクトリをスキャン
2. コンテキストで利用可能なスキルリストを公開
3. エージェントはタスクに応じてスキルを自動選択
4. SKILL.md のコンテンツをオンデマンドでロード

このメカニズムにより、すべてのルールを一度にロードすることを避け、パフォーマンスとコンテキスト利用率を向上させます。

Skill の中核構造

Skills の中核は次のとおりです：1つのフォルダ + 1つの SKILL.md ファイル。

SKILL.md ファイルには以下が含まれます：

• メタデータ（少なくとも名前と説明が必要）
• AI に特定のタスクの完了方法を指示する命令

Skill は本質的に 1 つの Markdown ファイルです（ファイル名は SKILL.md に固定）

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

SKILL.md 基本テンプレート:

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

# PDF 处理

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

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

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

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

最小必須項目の例:

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

オプションフィールドを含む例:

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

参考資料、参考例、実行スクリプトが必要な場合は、より複雑な Skill のディレクトリ構造を使用できます：

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

スキルの仕組み

スキルは段階的ロードを使用してコンテキストを効率的に管理します：

• 検出：起動時、AI は各スキルの名前と説明のみをロードし、最も基本的な識別情報だけを保持します。
• アクティベーション：タスクがスキルの説明に一致したとき、AI は完全な SKILL.md の指示をコンテキストに読み込みます。
• 実行：AI は指示に従って実行し、必要に応じて参照ファイルをロードしたりコードを実行したりします。

この設計により、AI は高速な応答を維持しながら、必要に応じて詳細な情報を取得できます。

ファイルの配置場所

各スキルには独立したフォルダが必要で、フォルダ内にSKILL.mdファイルを配置します（注意：ファイル名はすべて大文字にすること）。OpenCode は以下の6つの場所を自動的に検索します：

典型的なプロジェクトディレクトリ構造は次のとおりです：

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

検出メカニズム

OpenCode のスキル検出は2つの階層に分かれています：

• プロジェクトローカルスキル：OpenCode は現在の作業ディレクトリから開始し、上方向にディレクトリツリーを階層ごとに走査します、Git ワークツリーのルートディレクトリに到達するまで続けます。このプロセスで、途中の各階層のディレクトリにある.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.md内の一致するすべてのスキルファイルを収集します。

• グローバルスキル：同時に~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.mdで定義されたすべてのグローバルスキルをロードします。

2つの階層のスキルはマージされ、エージェントに提供されます。プロジェクトローカルスキルとグローバルスキルが同名の場合、プロジェクトローカルスキルが優先されます。

SKILL.md の作成

1、Frontmatter フィールド

各SKILL.mdファイルは YAML frontmatter で始まる必要があります（つまり---<<<SEP>>> <<<SEP>>> で囲まれた部分）。OpenCode は以下のフィールドのみを認識し、未知のフィールドは自動的に無視されます：

2、命名規則

nameフィールドの値は以下のすべての条件を同時に満たす必要があります。満たさない場合、スキルはロードされません：

• 長さは1〜64文字
• 含めることができるのは小文字と数字のみです。単語間は単一のハイフン（-）で区切ることができます
• で始まったり終わったりすることはできません-先頭または末尾
• 連続する--
• そのSKILL.mdのを含むフォルダ名と完全に一致する必要があります

等価な正規表現：

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

有効な命名例：git-release、api-doc、code-review、deploy2prod

無効な命名例：Git-Release（大文字を含む）、-release（-で始まる）、git--release（連続--）

3、説明文の作成

descriptionフィールドの内容は、エージェントがそのスキルを正しく選択して呼び出せるかどうかに直接影響します。説明は具体的かつ明確にすることをお勧めします。、そのスキルが何をするか、どのようなシナリオで使用するかを説明し、あまりに曖昧な記述は避けてください：

• ❌ 曖昧すぎる：リリースタスクの完了を支援する
• ✅ 具体的で明確：从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4、完全な例

プロジェクト内に作成.opencode/skills/git-release/SKILL.md、内容は次のとおりです：

Frontmatter 内のname値はフォルダー名と一致している必要があります。この例ではフォルダー名はgit-release、したがってnameも記述する必要がありますgit-release、そうでないとスキルは認識されません。

エージェントはどのようにスキルを発見・ロードするか

OpenCode を起動すると、現在利用可能なすべてのスキルが XML 形式でskillツールの説明に注入されます。エージェントはツールの説明を確認することで、どのスキルが利用可能かを把握できます：

<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>

エージェントが特定のスキルが現在のタスクに関連すると判断した場合、能動的にskillツールを呼び出して、そのスキルの完全なSKILL.md内容を読み込みます：

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

読み込みが完了すると、スキル内で定義された指示とコンテキスト情報はエージェントの作業記憶に入り、その後の動作と出力に影響を与えます。スキル自体は何も自動的に実行せず、エージェントに追加のコンテキストと行動規範を提供するだけです。

スキル権限の設定

にopencode.jsonでは、permission.skillフィールドを使用して、エージェントがアクセスできるスキルを制御し、完全一致と Glob ワイルドカードの2つのマッチング方式をサポートしています：

3つの権限アクションがスキルに与える具体的な効果は次のとおりです：

エージェントごとに権限を上書き

エージェントによってアクセスが必要なスキルセットは異なる場合があるため、エージェントごとに権限を個別に設定し、グローバルなデフォルト値を上書きできます。

1、カスタムエージェントの Frontmatter で設定

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

2、opencode.json で組み込みエージェントに設定

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

スキルツールの無効化

スキルをまったく使用しないエージェントの場合は、直接skillツールを無効にできます。無効にすると、<available_skills>リストはエージェントのコンテキストから完全に削除され、トークン消費を節約し、エージェントがスキルを読み込もうとするのを防ぎます。

1、カスタムエージェントの Frontmatter で無効化

2、opencode.json で組み込みエージェントに無効化

スキルのロード問題のトラブルシューティング

スキルが利用可能なリストに表示されない場合は、次の順序で項目ごとに確認してください：

1. ファイル名の大文字小文字を確認

   SKILL.mdのファイル名はすべて大文字で記述する必要があり、skill.md 或 Skill.mdと書いても認識されません。

2. Frontmatter の完全性を確認

   確認してくださいSKILL.md先頭に正しい YAML frontmatter があり、nameとdescription2つの必須フィールドが含まれていること。どちらかが欠けている場合、スキルは読み込まれません。

3. スキル名が一意で形式が正しいことを確認

   異なるパスに同じ名前のスキルが存在すると、競合が発生する可能性があります。同時にnameフィールドが命名規則（小文字の英数字のみ、ハイフン区切り）に適合しているか、またフォルダー名と完全に一致しているかを確認してください。

4. 権限設定を確認

   にopencode.jsonのpermission.skillでは、権限が"deny"のスキルはエージェントから完全に隠され、<available_skills>リストには表示されません。ワイルドカードルール（例："*": "deny"）がこのスキルに誤ってマッチしていないか確認してください。

詳細な Skills については、以下を参照してください：

• Skills チュートリアル：https://www.example.com/ai-agent/skills-agent.html