SKILL.md ファイル

SKILL.md は Agent Skills の中核ファイルです。

このセクションでは、SKILL.md の完全な構造と利用可能なすべてのフィールドについて詳しく説明します。

基本構造

SKILL.md ファイルには、次の2つの主要な部分が含まれます：

  1. YAML Frontmatter（メタデータ領域）
  2. Markdown コンテンツ（インストラクション領域）

完全な例

---
name: my-skill
description: スキルの説明。このスキルをいつ使用するかを示します。
license: Apache-2.0
compatibility: Python が必要3.10+
metadata:
  author: your-name
  version: "1.0"
---

# スキル名

ここにスキルの詳細な指示を記述します。...

## ステップ1

具体的な操作手順...

## ステップ2

その他の操作手順...

メタデータフィールドの詳細

SKILL.md でサポートされているすべてのメタデータフィールドは次のとおりです：

フィールド 必須 制約
name である 最大64文字。小文字、数字、ハイフンのみ使用可能。ハイフンで始まるまたは終わることはできません。
description である 最大1024文字。スキルの機能と使用シナリオを説明します。
license 否 ライセンス名、またはバンドルされたライセンスファイルへの参照
compatibility 否 最大500文字。環境要件（対象製品、システムパッケージ、ネットワークアクセスなど）を説明します。
metadata 否 追加のメタデータを格納するための任意のキーと値のペア
allowed-tools 否 スペース区切りの事前承認済みツールリスト（実験的機能）

name フィールドの詳細

name フィールドはスキルの識別子であり、次のルールに従う必要があります：

  • 長さ：1〜64文字
  • 文字制限：Unicode の小文字（a-z）とハイフン（-）のみ使用可能
  • 先頭と末尾：ハイフンで始まるまたは終わることはできません
  • 連続文字：連続したハイフン（--）を含めることはできません
  • 一致要件：親ディレクトリ名と一致する必要があります

有効な例：

name: pdf-processing
name: data-analysis
name: code-review

無効な例：

name: PDF-Processing   # 错误：不能使用大写字母
name: -pdf           # 错误：不能以连字符开头
name: pdf--processing  # 错误：不能包含连续连字符

description フィールドの詳細

description フィールドは最も重要なフィールドの1つであり、エージェントにこのスキルをいつアクティブ化すべきかを伝えます。

良い説明は次のことを行う必要があります：

  • スキルの機能を説明する（何をするか）
  • 使用シナリオを説明する（いつ使うか）
  • エージェントが関連タスクを識別するのに役立つキーワードを含める

良い説明の例：

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

悪い説明の例：

description: 帮助处理 PDF 文件。  # 太笼统，代理无法判断何时使用

ヒント：description フィールドは会話の開始時に読み込まれます。エージェントがスキルをアクティブ化するタイミングを正しく識別できるように、十分なキーワードが含まれていることを確認してください。

license フィールドの詳細

license フィールドはスキルのライセンスを指定するために使用します。これはオプションフィールドです。

license: Apache-2.0
# 或者引用 bundled 的许可证文件
license: Proprietary. LICENSE.txt has complete terms

compatibility フィールドの詳細

compatibility フィールドはスキルの環境要件を説明するために使用します。スキルに特別な環境要件がある場合にのみ追加する必要があります。

# 指定目标产品
compatibility: Designed for Claude Code

# 指定系统依赖
compatibility: Requires git, docker, jq, and access to the internet

# 指定编程语言版本
compatibility: Requires Python 3.14+ and uv

注意：ほとんどのスキルには compatibility フィールドは必要ありません。スキルに特定の環境要件が実際にある場合にのみ追加してください。

metadata フィールドの詳細

metadata フィールドには任意のキーと値のペア情報を格納できます。クライアントはこれを使用して、仕様で定義されていない追加の属性を格納できます。

metadata:
  author: example-org
  version: "1.0"
  tags:
    - pdf
    - document
    - extraction

ヒント：他のスキルとの衝突を避けるために、比較的ユニークなキー名を使用することをお勧めします。

allowed-tools フィールドの詳細

allowed-tools は、スキルが使用できる事前承認済みツールを指定するための実験的フィールドです。

allowed-tools: Bash(git:*) Bash(jq:*) Read

注意：これは実験的な機能であり、エージェントの実装によってサポートレベルが異なる場合があります。

インストラクション領域の詳細

メタデータ領域の後の Markdown コンテンツは、スキルのインストラクション部分です。ここには形式の制限はなく、必要に応じて任意のコンテンツを記述できます。

次の内容を含めることをお勧めします：

  • ステップバイステップの操作手順
  • 入力と出力の例
  • 一般的なエッジケースの処理
# 技能名称

## 功能说明

简要描述这个技能做什么。

## 操作步骤

1. 第一步：执行某个操作
2. 第二步：执行另一个操作
3. 第三步：完成最终操作

## 示例

### 输入示例
描述输入是什么...

### 输出示例
描述输出是什么...

## 注意事项

- 注意点 1
- 注意点 2

注意：スキルがアクティブ化されると、SKILL.md ファイル全体がコンテキストに読み込まれます。主要な指示は500行以内、5000トークン以下に保つことをお勧めします。詳細な参考資料は別のファイルに移動してください。

その他の拡張機能