Claude Code のスキル (skill) は、繰り返される手順や専門知識を SKILL.md ファイル 1 つに束ねて Claude のツールボックスへ追加する拡張メカニズムです。

背景リファレンス

このページは、MoAI-ADK が動作する基盤である Claude Code そのもの を解説する背景資料です。MoAI-ADK の使い方は スキルガイド で扱い、ビルダーエージェントでスキルを自動生成する手順は ビルダーエージェントガイド へ続きます。

情報

ひとことで言うと: チャットに毎回貼り付けていたチェックリストや手順を SKILL.md 1 枚にすれば、Claude が必要なときだけその内容を取り出して使う「ポケットの中の専門家」になります。

スキルは、Claude が従うべき指示を収めた SKILL.md ファイルです。ファイルを 1 つ作っておけば、Claude が関連する状況で自動的に呼び出して使うか、ユーザーが /スキル名 の形で直接呼び出せます。

次のような状況がスキルを作るサインです。

• 同じ指示やチェックリストをチャットに繰り返し貼り付けているとき
• CLAUDE.md のあるセクションが「事実情報」ではなく「複数段階の手順」に育ってしまったとき

CLAUDE.md の内容は常にコンテキストに常駐しますが、スキル本文は実際に使われるときだけロードされます。したがって長く詳細な参照資料を置いても、必要になるまでトークンコストはほとんどかかりません。

スキル以前は .claude/commands/ ディレクトリにカスタムコマンドを置くのが一般的でした。現在は スキルがコマンド機能を包含 するため、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md の両方があればスキルが優先されます。既存のコマンドファイルもそのまま動作しますが、新しい拡張はスキルとして書くことが推奨されます。

各スキルは SKILL.md をエントリーポイントとするディレクトリです。本文は YAML フロントマターとマークダウンの指示で構成され、補助ファイルを一緒に置けます。

my-skill/
├── SKILL.md       # 必須: 指示 + フロントマター
├── reference.md   # 任意: 詳細な参照 (必要なときにロード)
├── examples.md    # 任意: 出力例
└── scripts/
    └── helper.py  # 任意: Claude が実行するスクリプト

フロントマターの大半は任意項目ですが、Claude がいつこのスキルを使うべきかを判断する description は事実上必須です。

---
name: api-conventions
description: このコードベースの API 設計パターン。エンドポイントを作成またはレビューするときに使用。
allowed-tools: Read Grep
---

API エンドポイントを作成するとき:
- RESTful な命名規則に従う
- 一貫したエラー形式を返す
- リクエスト検証を含める

主なフロントマターフィールドは次のとおりです。

スキルの中核となる設計は、必要な分だけ段階的に見せる 段階的開示 (Progressive Disclosure) です。コンテキストウィンドウを節約しながらも、深い知識を保管する方式です。

flowchart TD
    A[メタデータ
description のみ常時ロード] --> B{関連する状況が
発生?}
    B -->|はい| C[本文
SKILL.md 全体をロード]
    C --> D{詳細資料が
必要?}
    D -->|はい| E[バンドルファイル
reference.md・スクリプトをロード]
    D -->|いいえ| F[本文だけで作業]
    B -->|いいえ| G[ロードしない
トークンコスト 0]

通常のセッションではすべてのスキルの description だけが常時ロードされ、Claude は「何があるのか」を知っており、実際の本文は呼び出された瞬間にのみ入ります。補助ファイルは SKILL.md からリンクで案内しておけば、Claude が必要なときだけ読みます。

Claude はユーザーのリクエストがスキルの description (および任意の when_to_use) と合致するとき、そのスキルを自動的に呼び出します。つまりトリガーは別の設定ではなく、説明文のキーワードマッチング です。

• ユーザーが自然に口にしそうなキーワードを description に含めるほど、うまくトリガーされます。
• 意図と無関係に頻繁にトリガーされすぎるなら、説明をより具体的に絞るか、disable-model-invocation: true で手動呼び出しのみを許可します。
• 直接呼び出したいときは /スキル名 の形で明示的に呼べばよいのです。

スキルが保存された場所が、使用範囲を決めます。

名前が重複した場合は、エンタープライズ > 個人 > プロジェクトの順で優先されます。プラグインスキルは プラグイン名:スキル名 形式の名前空間を使うため衝突しません。

以下は、未コミットの変更を要約するスキルです。!`git diff HEAD` 構文は、Claude が見る前にコマンドを先に実行し、結果を本文に埋め込む動的コンテキスト注入です。

---
description: コミットされていない変更を要約し、リスク要素を表示する。何が変わったかを尋ねるときに使用。
---

## 現在の変更内容

!`git diff HEAD`

## 指示

上記の変更を 2〜3 個の箇条書きで要約したうえで、欠落したエラー処理やハードコーディングなどのリスクを列挙する。

このスキルは、ユーザーが「何を変えたっけ?」と尋ねると自動的に、または /summarize-changes で直接呼び出されます。

MoAI-ADK はこのスキルメカニズムの上で動作します。moai-foundation-core、moai-workflow-spec のような汎用スキルが SPEC ワークフローと品質ゲートの知識を収めており、プロジェクトのドメインに合わせたスキルはビルダーエージェントが自動生成します。

スキルは MoAI-ADK の観点で 2 つの領域に同時にまたがっています。トークノミクス の面では、段階的開示はまさにトークン予算の設計です — 説明 1 行 (~100 トークン) だけを常時負担し、本文 (~5K トークン) は使用時点でのみ支払うため、知識を CLAUDE.md に常駐させるよりはるかに経済的です。再帰的な自己学習 の面では、スキルはハーネス進化の編集対象です — ループが蓄積した観察をもとにハーネスがスキル指針をアップグレードすることが、MoAI-ADK の自己進化の中核経路です。作成ルール・名前空間・段階的開示のトークン予算といった実践的な詳細は、以下の MoAI-ADK 応用ドキュメントを参照してください。

• スキルガイド
• ビルダーエージェントガイド

• Claude Code 公式ドキュメント — Extend Claude with skills

ヒント

スキルが期待どおりにトリガーされないときは、/doctor で説明文の予算が超過していないか確認し、description にユーザーが実際に入力しそうなキーワードが入っているかを点検してみてください。