> ## Documentation Index
> Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.
# Skill
> ワークフローをSKILL.mdと補助ファイルからなるディレクトリにまとめ、AIエージェントが必要なときだけ読み込む単位にします。誰が呼び出しても同じ手順が再現されます。
## 概要
SkillはAIエージェントのための再利用可能なワークフローの単位です。必須の`SKILL.md`ファイルと任意の補助ファイルからなるディレクトリとして定義し、`SKILL.md`に手順を書き起こします。すなわち、ステップごとのガイダンス、固定された出力フォーマット、そして本当に人の判断が必要な決定点です。
一度書けば、コマンドで呼び出すか自動発火で実行され、誰が実行しても同じような結果を生み出します。
本ページでは、Skillの背後にある原則、構造、そして作り方・呼び出し方を解説します。
## 設計の原則
Skillの目的は、実務に必要な文脈、すなわち組織固有の専門知識と手順をエージェントに渡すことです。その設計は次の4つの原則に立っています。
組織やチーム固有の手続き的知識をバージョン管理できる形で書き起こし、エージェントが推測ではなく渡された文脈に基づいて動けるようにします。
複数ステップのタスクを、誰が実行しても同じ手順をたどる、一貫した監査可能な手続きに変えます。
一度書けば、Skillに対応したどのエージェント・どの製品でも同じSkillを使えます。
起動時に読み込まれるのは`name`と`description`だけで、本文と補助ファイルは必要になったときにのみ読み込まれます。
## Skillの構造
Skillは専用のディレクトリ（Claude Codeでは`.claude/skills//`）に置き、`SKILL.md`ファイルと任意の補助ファイルで構成します。
### ディレクトリ構成
```text ディレクトリ構成 theme={null}
.claude/skills/
└── commit-message/
├── SKILL.md # 必須。frontmatter + 指示
├── references/ # 任意。本文からリンクされたときだけ読まれる
│ └── semantic_versioning.md
└── scripts/ # 任意。実行されるだけでコンテキストには載らない
└── check_format.sh
```
| 部分 | 役割 |
| ------------- | ------------------------------------------------------------------ |
| `SKILL.md` | 必須のファイルです。Skillを識別するfrontmatterと、エージェントへの指示を書きます。 |
| `references/` | 任意の補助ドキュメントです。ルールの全表・テンプレート・長い例などを置き、本文からリンクして必要なときだけ読み込ませます。 |
| `scripts/` | 任意のユーティリティスクリプトです。本文からエージェントに実行させます。コンテキストに入るのは出力だけで、ソースは読み込まれません。 |
### SKILL.mdの構成
`SKILL.md`は2つの部分から成ります。Skillを識別するYAML frontmatterと、指示と例を書くMarkdown本文です。
```md SKILL.md theme={null}
---
name: commit-message
description: Generate commit messages that follow semantic versioning rules. Use when committing changes or when asked to write a commit message.
---
# Instructions
1. Inspect the staged diff and classify the change as major, minor, or patch.
2. Combine it with a type prefix (feat, fix, docs, ...) per
references/semantic_versioning.md.
3. Output a single-line message in the form `-: `.
```
| 部分 | 役割 |
| --------------- | ---------------------------------------------------------------------------------- |
| `name` | ディレクトリ名と一致させる識別子で、呼び出しコマンド名（Claude Codeでは`/commit-message`）もここから取られます。 |
| `description` | Skillが適用される条件です。エージェントはリクエストをこのテキストと照合するため、Skillが発火するかどうかを左右します。 |
| `allowed-tools` | 任意です。Skillに許可するツールの一覧です。実験的なフィールドのため対応状況は実装により異なります。絞り方は後述の「ツール権限を最小にする」を参照してください。 |
| 本文 | Skillが有効になったあとにエージェントが従う指示です。手順・出力フォーマット・例を書きます。 |
### Progressive disclosure
Skillは一度にすべて読み込まれるのではなく、段階的に読み込まれます。セッション開始時にエージェントが読むのは、インストール済みSkillのfrontmatterだけです。本文はリクエストが`description`に合致したときに読まれ、`references/`配下のファイルは本文が参照した場合にのみ読まれます。
システムプロンプトやMCPのツール定義に置けば常にコンテキストを占有する指示が、必要になる瞬間までほぼコストゼロになります。
## Skillの作り方
### 発見されるための命名とdescription
`name`と`description`は、Skillが選ばれる前に読み込まれる唯一の部分です。発見されるかどうかは、この2つにかかっています。
* Skill名は動作を表す小文字とハイフンで付けます。`helper`や`utils`のような曖昧な名前は避けます。
* `description`は三人称で書き、Skillが何をするかといつ使うかの両方を述べ、ユーザーが実際に言いそうな言葉を含めます。
### 賢い読み手に向けて書く
エージェントは一般的なプログラミング知識をすでに持っています。書くべきは、エージェントが推測できないことだけです。つまり、自分たちの規約・制約・手順です。
簡潔な指示のほうが網羅的な指示より良い結果を出します。
* `SKILL.md`の本文はおよそ500行以内に保ちます。かさばる資料は`references/`のファイルへ移します。
* 参照は1階層に留めます。補助ファイルはすべて`SKILL.md`から直接リンクします。参照の連鎖が深いと、途中のファイルが部分的にしか読まれなくなります。
* 1つの概念には1つの用語を使い続けます（「フィールド」「ボックス」「要素」を混在させず、常に「フィールド」と書きます）。
* 時間に依存する記述（「8月までは旧APIを使う」など）は避けます。気づかないうちに誤りになります。
* 「MUST」「NEVER」「ALWAYS」といった強調の多用は黄色信号です。禁止を並べるより、なぜそうするのかという理由を書くほうが、想定外の場面でもエージェントが適切に判断できます。
* 本筋から外れるケース（引数が渡されない、外部サービスがエラーを返すなど）での動きも書いておきます。手順が正常系だけだと、例外時の挙動が実行のたびに変わります。
### 出力フォーマットをテンプレートで用意する
出力の一貫性が重要なSkillには、出力フォーマットのテンプレートを用意します。厳密さはタスクに合わせて調整し、構造の参考例を示すだけにも、常にそのとおり出力させる厳密なテンプレートにもできます。
* 後続の処理やツールが出力の形式に依存する場合（データフォーマット・定型レポートなど）は、常にこの構造で出力すると明記した厳密なテンプレートを使います。
* 内容に応じて構成が変わってよい場合は、参考のデフォルトとして示し、状況に合わせて調整してよいと添えます。
```md 厳密なテンプレートの例（レポート生成の場合） theme={null}
## Report structure
ALWAYS use this exact template structure:
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
## Recommendations
1. Specific actionable recommendation
```
### 入出力の例で示す
スタイル・トーン・詳細度のような、言葉では説明しにくい要素は、入出力のペアで示します。望ましい出力を説明で伝えるより、例で見せるほうが確実に伝わります。
```md 本文での例示（commit-messageの場合） theme={null}
# Examples
- Input: fix a typo in the README installation steps
Output: `patch-docs: fix typo in installation steps`
- Input: add JWT-based login to the auth service
Output: `minor-feat: add JWT login to auth service`
```
常に同じ構造で出力させたい場合は、例ではなく前項のテンプレートを使います。また、例は本文が読み込まれるたびにコンテキストを消費するため、長い例や多数の例は`references/`のファイルへ分離し、必要なときだけ読ませます。
### 自由度を壊れやすさに合わせる
タスクの壊れやすさに応じて、指示が残す裁量の幅を決めます。
コードレビューや分析のように複数のアプローチが有効な場面では、判断の指針を示してエージェントに経路を選ばせます。マイグレーションやリリース手順のように壊れやすく一貫性が必須の操作では、正確なコマンドを示し、変更してはならないと明記します。
複数のツールが使える場面では、デフォルトを1つ指名し、それが使えないケースに限って代替を添えます。
### ツール権限を最小にする
Skillに許可するツールは、ワークフローで実際に使うものだけに絞ります。Claude Codeでは、`SKILL.md`のfrontmatterに`allowed-tools`として宣言します。
```yaml theme={null}
allowed-tools: Read, Glob, Bash(git status*), Bash(git diff*)
```
* 手順に登場しないツールは許可しません。読み取りだけで完結するSkillにWriteやEditは不要です。
* Bashはコマンド単位で絞ります。`Bash(git *)`のような広い指定は、`Bash(git status*)`と`Bash(git diff*)`のような個別指定に分割します。
* `rm`や`git push --force`のような破壊的コマンドは原則許可しません。
知識の提供だけを行い、ツールを使わないSkillであれば、`allowed-tools`の宣言自体が不要です。
### 検証を組み込む
複数ステップのSkillは、チェックポイントがないと逸脱します。次の2つのパターンが軌道を保ちます。
* **チェックリスト。** Skillにステップ一覧を出力させ、進行に合わせてチェックさせます。飛ばされたステップが見えるようになります。
* **フィードバックループ。** 各出力に検証ステップ（バリデータのスクリプト・lintの実行・チェックリスト照合）を対にし、合格するまで修正と再検証を繰り返してから次へ進むよう指示します。
### サブエージェントを束ねる
ステップの多いSkillは、1つのエージェントに全手順を実行させるより、Skill本文を進行役（オーケストレーター）にして、独立したサブタスクをサブエージェントへ切り出すほうが安定します。
* 依存関係のないサブタスクは並列に実行させます。観点別のレビューや複数領域の調査を、順番に行う理由はありません。
* 各サブエージェントへの指示は自己完結させます。サブエージェントは呼び出し元の会話を見られないため、必要な文脈はすべてプロンプトで渡します。
* 並列実行のあとには、結果を統合するステップを必ず置きます。
* ステップをまたぐデータの受け渡し（前のステップの出力を次のどのステップで使うか）を本文に明記します。
並列にする数は数個程度に留めます。多すぎると、統合のコストが並列化の利得を上回ります。
### skill-creatorで作成する
skill-creatorは、新しいSkillの執筆を支援するAnthropic製のツールです。Claude Codeでは公式マーケットプレイスからインストールします。
```text theme={null}
/plugin install skill-creator@claude-plugins-official
```
作りたいSkillを説明すると対話フローが始まります。
skill-creatorは目的とSkillが確認すべき判断点を確かめたうえで、本ページで説明した構造どおりにディレクトリ（`SKILL.md`・`references/`のファイル・必要に応じて`scripts/`）を生成し、不要になったファイルを整理します。
## Skillの呼び出し
Skillの呼び出し方は2通りです。コマンドで明示的に呼ぶ方法と、エージェントがリクエストを`description`と照合して自動的に発火させる方法です。
どちらの経路でも同じ`SKILL.md`が実行されます。コマンドは直接のハンドルにすぎません。
Skillは単発のタスクに限定されません。本文で、確認の質問を挟み、サブエージェントを並列に走らせ、他のSkillをステップとして呼び出す、長い対話的なフローを駆動できます。
Skillが前提とする協働の基礎は[Vibe Coding](/ja/ai/vibe-coding)を、複数ステップのSkillが活躍する委任型の開発モデルは[Agentic Workflow](/ja/ai/agentic-workflow)を参照してください。