Skills 基本構造

Skills の核心的な本質は、AI に標準化された実行プロセスを定める操作ガイドラインであり、いったんルールを記述すれば、プログラムの関数のように繰り返し呼び出し、直接再利用できます。

Skills は Markdown テキスト形式で保存され、それ自体が直接機能を実行するわけではありません。

Skills はオンデマンド読み込み・段階的呼び出しの特性により、業務経験を効率的に蓄積し、能力の迅速な再利用と的確な伝達を実現します。


Skill の核心構造

Skills の核心とは:1つのフォルダ + 1つの SKILL.md ファイル。

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

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

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

my-skill/
└── SKILL.md   (唯一必需)

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

---
name: your-skill-name
description: 一句话描述该 Skill 的功能和使用场景
---

# Skill 名称

## 使用指引
[给 AI 的分步骤行为指引]

## 示例
[该 Skill 的具体使用示例]

SKILL.md 全体は上下2つの部分に分かれます:------ で囲まれた YAML frontmatter(ヘッダー設定)、およびその下の Markdown 本文(実行手順)です。

フィールド必須説明例
nameであるSkill の一意の識別子で、kebab-case で命名します。/ コマンドから参照され、システムが Skill を識別するための重要なフィールドです。web-design-guidelines
descriptionである機能とトリガーシナリオを一文で説明します。内容が具体的であるほど、トリガーが正確になります。UI/UX design review for web pages

次に、各部分を一つずつ詳しく見ていきます:

Frontmatter: 必須フィールド2つ

Frontmatter は SKILL.md の上部にある --- で囲まれた YAML 設定ブロックで、Skill 全体の識別情報です。

公式では必須フィールドは2つだけと定められています:

フィールド1: name(スキル名)

name フィールドは最大64文字で、小文字のアルファベット、数字、ハイフンのみを含めることができます。

name: processing-pdfs        # 好:动名词形式,清晰描述功能
name: analyzing-spreadsheets # 好:一眼知道用途
name: my-brand-guidelines    # 好:组织专属知识

name: helper      # 差:太模糊
name: MySkill     # 差:包含大写字母(不合规)
name: data files  # 差:包含空格(不合规)

動名詞形式(動詞 + -ing)での命名を推奨します。例: processing-pdfs、analyzing-spreadsheets。これにより、Skill が提供する活動や能力を明確に説明できます。

推奨非推奨理由
code-reviewerCodeReviewer小文字とハイフンを統一して使用し、クロスプラットフォームの互換性問題を回避します
sql-optimizersql_optimizerkebab-case は慣習的な形式であり、ディレクトリ名と一致させます
deploy-checkdeploy-check-tool-v2名前は簡潔にし、バージョン情報はファイル内部の説明に記載します

フィールド2: description(トリガー条件の説明)

これは最も重要なフィールドです。起動時、システムはすべての Skills の name と description だけをシステムプロンプトにプリロードします。

AI が description を現在のタスクに関連すると判断した場合にのみ、完全な SKILL.md の内容がさらに読み込まれます。

description には次の2つの部分を両方含める必要があります:この Skill が何をするか、そしていつ Claude がそれを使用すべきか。

description: |
  Use when the user needs to create, read, edit, or generate Word
  documents (.docx). Triggers include: 'Word doc', 'word document',
  '.docx', 'report', 'letter', 'memo', or any request to produce
  a formatted document for sharing or printing.

Markdown 本文: 実行手順の内部構造

推奨非推奨理由
「Python コードの SQL インジェクションリスクをスキャンし、修正提案を提供する」「セキュリティツール」説明が曖昧すぎて、正確にトリガーできません
「Markdown をブランドガイドラインに適合する HTML メールに変換する」「ファイル形式の変換」具体的なシナリオが不足しており、他のタスクで誤ってトリガーされる可能性があります

Frontmatter の後は Markdown 本文で、AI に具体的な手順を指示します。

少なくとも2つのブロックを含みます:

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

フィールド説明:

フィールド 必須 説明
name である Skill 名。最大64文字で、小文字のアルファベット、数字、および-ハイフンのみ使用できます。また、ハイフンで-始まったり終わったりしてはいけません。
description である 機能と使用シナリオの説明。最大1024文字で、空にすることはできません
license 否 ライセンス名、または Skill に同梱されるライセンスファイルを指すパス
compatibility 否 環境と依存関係の説明(製品、システムパッケージ、ネットワーク権限など)。最大500文字
metadata 否 カスタムキーバリューペア。メタデータの拡張に使用します(例: 作者、バージョン番号)
allowed-tools 否 使用を許可するツールのリスト(スペース区切り、実験的機能)

Skill のファイルディレクトリ構成

1つのスキルは1つのフォルダであり、少なくとも1つの SKILL.md ファイルを含みます。必要に応じて、他のディレクトリやファイルも含めることができます。

コンテキストの膨張を避けるため:

  • コアルール →SKILL.md
  • 詳細情報 → 個別ファイル
  • 実用ロジック → スクリプトで実行(読み込まない)

推奨される構成:

my-skill/
├── SKILL.md          # 必需:元数据 + 指令
├── scripts/          # 可选:可执行代码
      └── helper.py
├── references/       # 可选:参考文档
├── assets/           # 可选:模板、资源
└── ...               # 其他文件或目录

各ディレクトリの役割は次のとおりです:

  • SKILL.md: 必須ファイル。スキルのメタデータと実行命令を含みます
  • scripts/: オプションのディレクトリ。エージェントが実行できる実行可能コードを含みます
  • references/: オプションのディレクトリ。詳細な参考資料を含みます
  • assets/: オプションのディレクトリ。テンプレート、画像などの静的リソースを含みます
その他の拡張