Claude Code には「スキル」という仕組みがあります。繰り返し使う手順やチェックリストをファイルに書いておくと、/skill-name で呼び出したり Claude が自動判断で使ったりできます。

スキルの書き方には 2 つの流派があります。Anthropic 公式ドキュメントが示すスタイルと、GitHub で公開されているコミュニティリポジトリで広まっているスタイルです。どちらも同じ SKILL.md フォーマットで動きますが、設計思想が異なります。

2 つのスタイル

公式スタイル：3 層構造

Anthropic 公式ドキュメントと公式 Cookbook が採用するスタイルです。

.claude/skills/
└── deploy/
    ├── SKILL.md          # フロントマター + 骨格のみの指示
    ├── checklist.md      # 詳細資料（必要時にロード）
    └── scripts/
        └── validate.sh   # スクリプト（実行時に使用）

SKILL.md 本体は骨格だけに絞り、詳細は補助ファイルへ分離します。補助ファイルは必要なときだけロードされるため、コンテキストコストを抑えられます。

コミュニティスタイル：単一ファイルの配布パッケージ

awesome-claude-code-toolkit などのコミュニティリポジトリで広まっているスタイルです。

.claude/skills/
└── deploy/
    ├── SKILL.md          # 必須・エントリポイント
    ├── checklist.md      # 補助ファイル（任意）
    └── scripts/
        └── validate.sh   # スクリプト（任意）

フロントマターに author / version / tags / repository / license などの配布用メタデータが追加されており、GitHub からそのままインストールして使えるパッケージとして設計されています。補助ファイルは持たず、SKILL.md 1 ファイルにすべてを記述します。

---
name: continuous-learning
description: Auto-extract patterns from coding sessions, track corrections, and build reusable knowledge with confidence scoring
author: example-author
version: 1.0.0
tags: [memory, productivity]
repository: https://github.com/example/skill
license: MIT
---

本文も詳細です。手順・データ構造・YAML スキーマ・具体例をすべて SKILL.md に書き込み、読み込んだだけで使える自己完結型になっています。

格納場所と有効範囲

場所 パス 適用範囲
個人 ~/.claude/skills/<name>/ 全プロジェクト
プロジェクト .claude/skills/<name>/ そのリポジトリのみ
プラグイン <plugin>/skills/<name>/ プラグイン有効な場所

優先順位は エンタープライズ > 個人 > プロジェクト です。

フロントマターのフィールド

SKILL.md の冒頭に YAML で書きます。全フィールドがオプションですが、description だけは実質必須です。

---
name: deploy
description: >
  本番環境へデプロイする。deploy, release, ship と言われたときに使う。
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(cargo *)
context: fork
agent: general-purpose
effort: high
paths: ["src/**", "Cargo.toml"]
---

よく使うフィールド

description：Claude が自動トリガーを判断する基準。「いつ使うか」の条件を英語か日本語で書きます。説明と when_to_use を合わせて 1,536 文字まで活用できます。

disable-model-invocation: true：Claude が勝手に呼び出さなくなります。デプロイ・コミット・外部送信など、タイミングを制御したい副作用のある操作に使います。

user-invocable: false：/ メニューに表示されなくなります。バックグラウンドの参照知識（レガシーシステムの仕様など）を Claude だけに渡したいときに使います。

allowed-tools：このスキルが有効な間、指定ツールの実行をユーザー確認なしで許可します。Bash(git *) のようにコマンドプレフィックスで絞れます。

context: fork：スキルをサブエージェントとして独立したコンテキストで実行します。メイン会話の履歴を汚さず調査や変換処理を走らせたいときに有効です。

paths：glob パターンにマッチするファイルを操作しているときだけ自動ロードします。モノレポでパッケージ固有のスキルを分けるときに使います。

動的コンテキスト注入

!`command` 構文を使うと、Claude がスキルを読む前にシェルコマンドが実行されてその出力が埋め込まれます。

---
description: コミット前の差分を要約して問題を指摘する
---

## 現在の差分

!`git diff HEAD`

## 指示

上記の差分を 3 点以内で要約し、エラーハンドリング漏れ・ハードコードされた値・更新が必要なテストを挙げてください。

Claude には「git diff の出力」が直接渡るため、自分でファイルを開く必要がありません。複数行コマンドは ```! フェンスで書けます。

これは前処理であり、Claude が実行するわけではありません。Claude が見るのはコマンド実行後の最終テキストだけです。

引数の受け渡し

$ARGUMENTS でスキル呼び出し時の引数を受け取れます。

---
name: fix-issue
description: GitHub Issue を修正する
disable-model-invocation: true
---

Issue $ARGUMENTS の要件を読み、修正→テスト→コミットまで行ってください。

/fix-issue 123 と打つと $ARGUMENTS が 123 に置き換わります。複数引数は $0, $1 のようにインデックスで参照できます。

公式スタイル vs コミュニティスタイル

観点 公式スタイル コミュニティスタイル
ファイル構成 SKILL.md + 補助ファイル SKILL.md 1 ファイル
ボディの長さ 骨格のみ（500 行以内推奨） 詳細まで全記述（長くなりがち）
フロントマター name / description / allowed-tools 等 + author / version / tags / repository / license
想定用途 プロジェクト固有の手順・チーム内共有 GitHub で配布・インストールして使う
トークンコスト 低（補助ファイルは遅延ロード） 高（全内容がセッション中ずっと乗る）

自分のプロジェクトや個人用に書くなら公式スタイルの 3 層構造が適しています。コミュニティから持ってきたスキルはそのまま動きますが、トークン消費が多い点は意識しておくといいでしょう。

まとめ

  • 公式スタイルは SKILL.md + 補助ファイルの 3 層構造。ボディは骨格のみ、詳細は遅延ロードで分離する
  • コミュニティスタイルは単一ファイルに全記述。配布・インストールを前提とした設計で、フロントマターに author / version 等の配布用メタデータを持つ
  • コマンド名はディレクトリ名から決まる。name フィールドは表示名のみ
  • description が自動トリガーの精度を左右する。「いつ使うか」の条件を明示的に書く
  • 副作用のある操作は disable-model-invocation: true で手動呼び出し専用にする
  • !`command` で動的なコンテキストを注入できる。Claude がファイルを開く手間を省ける
  • context: fork でサブエージェントに移譲できる。調査・変換系のタスクに向いている

出典