解説
Claude Skills とは
スキルは SKILL.md を入れたフォルダです。frontmatter が「何を・いつ」を決め、本文が手順を書きます。このページでは、ファイルの中身・読み込みの条件・インストール・作り方までをまとめます。
結論から
スキルとは、SKILL.md を入れたフォルダです。ファイルは2つの部分でできています。
---
name: pdf
description: PDF の読み取り・分割・結合・フォーム入力を行う。PDF を扱うタスクのときに使う。
---
# PDF
エージェントが従う手順・確認項目・例…
- frontmatter(
name/description)はメタ情報です。このdescriptionがトリガーになります。 - 本文は手順書です。何を、どの順で、どこを確認するか。
- 必要ならスクリプトや素材を同じフォルダに置き、本文から呼び出します。
Claude Code、Codex、Cursor などのエージェントは、スキルを必要なときだけ読み込みます。だからこそ、説明文の精度がすべてです。
読み込みはどう決まるか
エージェントはあなたの依頼文と description を照合します。語彙が一致すれば読み込み、一致しなければディスクに残ったままです。
失敗は2パターンに集約されます。
- 説明文が曖昧(「文書に役立つスキル」)→ 一致せず発動しない。
- 説明文は的確だが、隣のスキルが勝つ → 別のスキルが読み込まれる。
つまり、インストールしたら説明文を読み、その語彙で依頼するのがコツです。「フォーム付きの PDF を作って」は PDF スキルを呼びますが、「書類を作って」では呼ばれないことがあります。
保存場所
| 範囲 | パス | 用途 |
|---|---|---|
| 個人 | ~/.claude/skills/<name>/SKILL.md |
すべてのプロジェクトで使う |
| プロジェクト | <project>/.claude/skills/<name>/SKILL.md |
そのリポジトリ専用 |
他のエージェントは独自のフォルダを使います。CLI は指定したエージェントの場所へ書き込みます。
インストール
npx skills add <owner>/<repo> --skill <name>
例:npx skills add anthropics/skills --skill pdf。エージェントを明示するなら -a claude-code(または -a cursor / -a codex)を付けます。詳しくはインストール手順へ。
自分で作る手順
- 仕事を1つに絞る。 3つのことをするスキルは、どれでも発動しません。
- frontmatter を書く。
nameはケバブケース、descriptionは「何を」+「いつ」を明記(「〜のときに使う」)。 - 本文を手順書にする。 順番・確認項目・実例を1つ。宣伝文は不要です。
- 必要なときだけスクリプトを足す。 参照はスキルフォルダからの相対パスで。
- トリガーを試す。 発動すべき依頼と、すべきでない依頼を1つずつ。誤爆したらまず説明文を直します。
公開前にSKILL.md バリデータで構造を確認できます。
スキル・MCP・サブエージェントの違い
| 仕組み | エージェントに与えるもの | 読み込み |
|---|---|---|
| スキル | 方法(手順と確認項目) | 説明文が一致したとき |
| MCP サーバー | 接続(ツールとデータ) | セッション開始時 |
| サブエージェント | 分離(独立したコンテキスト) | 委任したとき |
| スラッシュコマンド | 明示的に呼ぶプロンプト | 入力したときだけ |
アクセスが必要なら MCP、方法が必要ならスキルです。
Community notes
Found a broken install? Know a skill we missed?
One line is enough: the skill name, what happened, and the command you ran. We read every note and fix the index.