Skills 設計パターン — SKILL.md の書き方とトリガー条件

読了 10分＋実践 35分

カスタムコマンドの設計を理解しており、Claude の自動動作をスキルとして定義したい方。[カスタムコマンド深掘り](./commands) を先に読むことを推奨します。

`shared/commands/` の仕組み・`.claude/` のシムリンク設定の基本

スキル（Skills）を適切に設計すると、Claude が特定のコンテキストで自動的に「このプロジェクトの書き方を知る専門家」として機能するようになります。このページでは、SKILL.md のフォーマット・設計原則・ディレクトリ構造・harness への登録方法を順番に学びます。

Skills とは何か

スキル（Skills）とは、Claude が特定のコンテキストで自動的に参照する「役割定義書」です。ユーザーが明示的に呼び出すコマンドとは異なり、Claude がタスクの性質を判断して適切なスキルをロードします。

スキルファイルは Claude のシステムプロンプトに自動的に追加されます。その結果、Claude は「汎用 AI として回答する」のではなく「このスキルで定義された役割・手順・ルールに従って動作する」ようになります。

Commands との違いを確認する

観点	Commands（/command）	Skills（SKILL.md）
トリガー	ユーザーが `/command` と入力する	Claude が状況を判断して自動ロードする
呼び出し	明示的・意図的	暗黙的・自動
用途	作業フロー全体の実行	特定コンテキストでの振る舞いの定義
ファイル場所	`shared/commands/*.md`	`shared/skills/*/SKILL.md`

コマンドは「何をするか」の手順書、スキルは「どのような専門家として振る舞うか」の役割定義書です。

SKILL.md のフォーマット

スキルファイルは frontmatter とボディで構成されます。

frontmatter の構造

---
name: skill-name
description: スキルの説明（Claude がスキル選択時に参照する）
metadata:
  short-description: 短い説明（一覧表示用）
---

name: スキルを識別する ID。ディレクトリ名と一致させます
description: Claude がどのタスクにこのスキルを使うか判断する際の説明
metadata.short-description: harness の一覧表示やログで使われる短い説明

ボディの構造

frontmatter の後に、Claude への指示をそのまま Markdown で書きます。

---
name: docs-content
description: プログラミング初心者向け学習教材ドキュメントの作成・更新・品質最適化スキル
metadata:
  short-description: 初心者向けドキュメント執筆・最適化手順
---

# ドキュメント執筆 & 学習教材最適化スキル

## 役割

あなたは、プログラミング・AI 分野の初心者向け学習教材を専門とするテクニカルライターです。

## 手順

1. 対象読者のレベルを確認する
2. ドキュメント種別を選択する（Tutorial / How-to / Reference / Explanation）
3. 既存構造・関連ページを把握する
...

## ルール

- 個人の経験談・感情的な表現を含めない
- 技術用語は初出時に定義する
...

このプロジェクトの shared/skills/docs-content/SKILL.md がこの形式の実例です。役割・執筆プロセス・品質チェックリストまで含む 650 行規模のスキルが定義されています。

ディレクトリ構造

スキルは1スキル1ディレクトリで管理します。

shared/
└── skills/
    ├── docs-content/
    │   └── SKILL.md          # ドキュメント作成スキル
    ├── blog-content/
    │   └── SKILL.md          # ブログ記事作成スキル
    ├── i18n-sync/
    │   └── SKILL.md          # i18n 同期スキル
    ├── pr-review/
    │   └── SKILL.md          # PR レビュースキル
    └── test-verify/
        └── SKILL.md          # テスト・検証スキル

.claude/
└── skills/                   # shared/skills/ へのシムリンク（自動同期）
    ├── docs-content.md  →  shared/skills/docs-content/SKILL.md
    ├── blog-content.md  →  shared/skills/blog-content/SKILL.md
    └── ...

shared/skills/ が source of truth です。.claude/skills/ はシムリンクを通じて自動同期されます。スキルを追加・更新するときは shared/skills/ 側だけを編集します。

ベストプラクティス

スキル名は具体的にする

汎用的な名前は避け、タスクドメインが明確に分かる名前にします。

良い例	避けるべき例
`blog-content`	`writer`
`pr-review`	`review`
`docs-content`	`docs`
`i18n-sync`	`sync`

Claude がスキルを選択する際、description フィールドと name を手がかりにします。具体的な名前は誤ったスキルの自動選択を防ぎます。

役割を1つに絞る

1スキル1責務の原則を守ります。「ドキュメント作成もブログ作成もできる」スキルは避け、docs-content と blog-content を別々のスキルとして定義します。責務が混在すると、Claude が期待外れの動作をするリスクが高まります。

手順は番号付きリストで書く

スキルのボディには明確な手順を番号付きリストで記述します。Claude は手順を上から順番に実行しようとするため、順序の明示が品質の安定につながります。

## 手順

1. スコープを確認する（対象読者・ドキュメント種別）
2. 既存ページとの重複・矛盾がないか確認する
3. 構成を設計する
4. 日本語ページを先に執筆する
5. ファクトチェックを実施する
6. 英語ページに翻訳・同期する

ルールセクションを設ける

スキルが守るべき制約・禁止事項を「ルール」セクションとして明記します。

## ルール

- `npm run build` はユーザーの明示承認なしに実行しない
- 個人の経験談・感情的な表現を含めない
- 日本語ページを先に作成・更新する（英語は後）
- 英語コンテンツで `we`/`our`/`us` を使わない（`I` を使う）

skill-waivers.md で例外を管理する

特定の状況でスキルをスキップしたい場合は、shared/skill-waivers.md に例外を記録します。スキルのルールを直接変更するのではなく、例外を別ファイルで宣言することで、通常のルールと例外の区別を明確に保てます。

実践演習

Step 1: 既存スキルの構造を確認する

cat shared/skills/docs-content/SKILL.md

frontmatter の name・description・metadata.short-description と、ボディの「役割」「手順」「ルール」セクションを確認します。

✅ 確認: ファイルの内容が表示され、frontmatter と役割・手順・ルールの各セクションが含まれていれば読み込み成功です。

Step 2: 新しいスキル `code-review/SKILL.md` を作成する

コードレビューに特化したスキルを新規作成します。

mkdir -p shared/skills/code-review

shared/skills/code-review/SKILL.md の内容：

---
name: code-review
description: プルリクエストのコードレビュースキル。変更の目的・影響範囲・セキュリティリスク・コーディング規約への準拠を検査する。
metadata:
  short-description: PR コードレビュー
---

# コードレビュースキル

## 役割

プルリクエストのコードレビューを担当する上級エンジニアとして、変更の品質・安全性・保守性を評価します。

## 手順

1. `gh pr view $PR --json title,body,files` で PR の概要を取得する
2. 変更されたファイルの diff を確認する
3. 以下の観点でレビューコメントを作成する：
   - 変更の目的が明確か
   - バグ・セキュリティリスクがないか
   - コーディング規約に準拠しているか
   - テストが十分か
4. レビュー結果を「Approve / Request Changes / Comment」の判定とともに報告する

## ルール

- 個人の好みではなく、客観的な根拠に基づいてコメントする
- 問題点だけでなく、良い点も積極的に指摘する
- 修正が必要な場合は具体的な改善案を示す
- セキュリティに関わる問題は最優先で報告する

✅ 確認: cat shared/skills/code-review/SKILL.md を実行して内容が表示されれば作成成功です。

Step 3: シムリンクを確認する

ls -la .claude/skills/

出力例：

docs-content.md -> ../../shared/skills/docs-content/SKILL.md
blog-content.md -> ../../shared/skills/blog-content/SKILL.md
...

✅ 確認: 既存スキルがシムリンク（->）として表示されていれば、アダプター層が正しく機能しています。新しく作成した code-review スキルは次の手順で harness に登録します。

Step 4: harness を同期・検証する

npm run harness:sync && npm run harness:check

harness:sync がシムリンクを更新し、harness:check が設定のドリフト（期待値との乖離）と安全ルール違反を検出します。

出力例：

✓ harness:sync complete
✓ 6 skills registered
✓ no drift detected
✓ harness:check passed

✅ 確認: harness:check passed が表示されれば、スキルが正しく登録されています。エラーが出た場合は SKILL.md の frontmatter（特に name フィールドとディレクトリ名の一致）を確認してください。

まとめ

Skills は Claude が自動ロードする役割定義書。Commands と異なり、ユーザーが明示的に呼び出す必要はない
SKILL.md は frontmatter（name・description・metadata）とボディ（役割・手順・ルール）で構成する
スキルは shared/skills/<name>/SKILL.md に配置し、.claude/skills/ はシムリンクで自動同期する
1スキル1責務の原則を守り、具体的な名前と明確な手順・ルールを記述することで、Claude の動作が安定する
npm run harness:sync && npm run harness:check でスキルの登録状態を確認する

次のステップ

Agents スペック設計 — スキルをさらに発展させ、サブエージェントの役割・制約を定義する方法を学ぶ
ハーネスのテストと検証 — スキルが意図通りに機能するかを体系的に検証する方法へ進む

よくある質問

Q: スキルはいつ自動的にロードされますか？

A: スキルのロードタイミングはハーネスの実装によって異なります。Claude Code の場合、description フィールドとタスクの内容をもとに Claude がどのスキルを参照するかを判断します。エージェントスペック（shared/agents/）でスキルを明示的に指定することで、特定のエージェントに特定のスキルを確実にロードさせることもできます。

Q: スキルのボディには何語で書くべきですか？

A: このプロジェクトでは日本語を source of truth としているため、スキルのボディも日本語で書きます。Claude は日本語の指示を正しく理解して動作します。

Q: スキルを削除した場合、何か追加の作業が必要ですか？

A: shared/skills/<name>/ ディレクトリを削除した後、npm run harness:sync を実行してシムリンクを更新します。その後 npm run harness:check で整合性を確認します。スキルが他のエージェントスペックや CLAUDE.md から参照されている場合は、それらのファイルからも参照を削除してください。

Q: 1つのタスクに複数のスキルを適用することはできますか？

A: できます。エージェントスペック（shared/agents/）で複数のスキルを参照することで、Claude が複数のスキルを組み合わせて動作します。ただし、スキル間でルールが矛盾しないよう注意が必要です。

クイズ

Agents スペック設計 — サブエージェントの定義と活用

カスタムコマンド深掘り — Skills との違いとベストプラクティス