「ドキュメントは整備したはずなのに、Claude Code が前提を守ってくれない」。 「同じ説明を、毎回プロンプトに書き直している」。 「チームで蓄えてきたナレッジが、結局は個人の頭の中にしか残っていない」。
このあたりのモヤモヤを抱えているマネージャーは、いま急速に増えています。原因はシンプルで、いまチームが持っているドキュメントの多くが「人間が読むことだけ」を前提に作られていて、Claude Code にそのまま渡しても動いてくれない形になっているからです。
ここで効いてくるのが、Claude Code Skills、いわゆるSKILL.mdの考え方です。SKILL.mdは「Claude Codeに守ってほしい業務標準を、実行可能なドキュメントとして書く」フォーマットだと捉えると、ぐっと使い道がイメージできるようになります。
この記事では、SKILL.mdとは何かをマネージャーの言葉で整理したうえで、チームのナレッジをSKILL.md化していくための考え方と、最初の1枚をどう書き始めるかをまとめます。
なぜ「人間向けドキュメント」では Claude Code が動かないのか
まず押さえておきたいのは、Claude Codeがドキュメントを「読むだけ」では足りない、ということです。
人間向けに書かれたドキュメントは、たいてい次の特徴があります。
- 背景・経緯・思想が長く、肝心の手順が後ろにある
- 「ケースバイケース」で済ませている記述が多い
- どの場面で使うべきかが、暗黙の前提になっている
- 用語が章ごとにブレている
人間なら「この章は読み飛ばしていい」「この用語は前のセクションのアレと同じ」と空気で補完できますが、Claude Codeは基本的に渡された前提を素直に処理します。結果として、ドキュメントが厚いほど、肝心のルールが薄まって守られなくなる、という逆転現象が起きます。
ここを「プロンプトを工夫して頑張る」で乗り切ろうとすると、依頼者ごとに品質がブレます。テックエイドの記事 Claude Codeへの依頼を4要素で書く｜目的・制約・出力形式・反証条件で手戻りを止める では「依頼の型」を整える話を扱いましたが、SKILL.mdはその一段上で「依頼そのものをチームの資産に積み上げる」アプローチだと思ってもらうとつながりが良いです。
SKILL.md は「実行可能なドキュメント」だと捉える
SKILL.mdをひとことで言うなら、「Claude Codeが呼び出すたびに、必ずその通りに動いてほしい運用知識を書き留めておく場所」です。
普通のドキュメントとの違いは、次の3点に集約できます。
1. 役割が「説明」ではなく「指示」
人間向けドキュメントは「こういうことです」と説明する役割を持ちますが、SKILL.mdは「こういう場面で、こう動け」という指示の集合として書きます。読み物ではなく、運用台本に近いイメージです。
2. 呼び出される前提で構造化されている
SKILL.mdは、Claude Codeから「このスキルを使いたい」と呼び出される前提で書きます。だから冒頭で「いつ使うスキルか」をはっきりさせ、続けて「やること」「やらないこと」「成果物の形」を明確に書きます。読み手（Claude Code）が、迷わず手順に入れる構造になっていることが重要です。
3. チームで使い回せる単位で切られている
SKILL.mdの一番の価値は、「同じ説明を毎回しなくてよくなる」ことです。 個人の頭の中にあった「弊社ではこうやる」「この案件ではこの順で進める」を、再利用可能な単位で切り出して保存できる。これは、ドキュメント文化とAI活用が同期する瞬間でもあります。
チームのナレッジを SKILL.md 化する手順
ここからは、実際にSKILL.mdを作っていくときの考え方を、マネージャー目線で整理します。最初から完璧を目指す必要はありません。
1. 「毎回説明していること」を3つ書き出す
最初に立派なナレッジマップを描く必要はありません。まずは自分やリーダーが「毎回同じことを説明している作業」を3つだけ書き出すことから始めましょう。
例として、こういうものがよく挙がります。
- 顧客への週次報告書のフォーマットと、書く順序のルール
- 障害発生時の一次対応フロー（連絡先・記録の取り方・エスカレーション基準）
- 見積もり依頼を受けたときの、確認すべき項目チェック
「毎回同じ説明をしている」という状況は、SKILL.mdに切り出すべきサインです。逆に、年に1回しかやらない作業までSKILL.mdにする必要はないでしょう。
2. 1ファイル1スキルとし、用途を冒頭に書く
選んだナレッジは、それぞれ別のSKILL.mdにします。1つのファイルに詰め込みすぎると、Claude Codeがどの場面で使うべきかを判断しづらくなり、結局守られなくなります。
ファイルの冒頭には、必ず次を書きます。
- このスキルが扱う作業（例：「週次報告書を書くスキル」）
- いつ使うか（例：「顧客向け週次定例の前日に、議事録から報告書を起こすとき」）
- 使わない場面（例：「内部向けの進捗共有では使わない」）
「使わない場面」を書くのがコツです。これがないと、Claude Codeは近そうな場面ですべて呼び出しに来てしまい、別の作業の邪魔をします。
実際の冒頭セクションはこのような形になります。
---
description: "顧客向けの週次報告書を、議事録から起こすスキル"
disable-model-invocation: false
---
## いつ使うか
顧客向けの週次定例の前日に、議事録ファイル（`docs/minutes/`配下）から
報告書ドラフトを生成するとき。
## 使わない場面
- 内部向けの進捗共有・社内定例には使わない
- 月次レポートや最終納品物の作成には使わない（フォーマットが異なる）この2セクションを書くだけで、Claude Codeはスキルの「守備範囲」を正しく把握できます。
3. 手順は順序立てた箇条書きで書く
本文は、長い文章ではなく、順序のある手順として書きます。
書くときの目安は次の通りです。
- 1ステップ1動作にする（「Aを確認し、Bを書き、Cに送る」を1ステップにしない）
- 判断が分岐するところは「もし〜なら」を明示する
- 出力例を最低1つ載せる
- 守ってほしい禁止事項は「やらないこと」として独立させる
例えば、週次報告書作成スキルを完全に書き起こすと、次のようになります。
---
description: "顧客向けの週次報告書を、議事録から起こすスキル"
disable-model-invocation: false
---
## いつ使うか
顧客向けの週次定例の前日に、`docs/minutes/YYYY-MM-DD.md` から
報告書ドラフトを生成するとき。
## 使わない場面
- 内部向けの進捗共有には使わない
- 月次レポート・最終納品物の作成には使わない
## 処理手順
1. `docs/minutes/` 配下の最新議事録ファイルを1件読み込む
2. 「決定事項」「懸案事項」「次回アクション」のセクションを抽出する
3. 以下の出力フォーマットで報告書ドラフトを生成する
4. 担当者名が不明なアクションには `[要確認]` を付記する
5. 完成したドラフトを `docs/reports/YYYY-MM-DD-weekly.md` に書き出す
## やらないこと
- 前回報告書の内容を参照して差分を埋めること（混同を防ぐため）
- 顧客名・金額・個人名を勝手に変更・省略すること
- 報告書をそのまま送付すること（人間のレビューが必要）
## 出力フォーマット
```markdown
# 週次報告書 YYYY-MM-DD
## 今週の完了事項
- （完了したタスクを箇条書き）
## 懸案事項
- （課題と対応方針を箇条書き）
## 来週のアクション
| アクション | 担当 | 期限 |
|---|---|---|
```この粒度まで落とすと、Claude Codeは「どこで何を判断すればいいか」を取り違えにくくなります。これは人間の新人にナレッジを引き継ぐときの粒度とほぼ同じで、SKILL.mdは実は「新人教育マニュアルの強化版」と捉えると書きやすくなります。
4. 「使う→直す」サイクルを当たり前にする
SKILL.mdは書いて終わりではありません。使ってみて期待と違ったら直す、というサイクルを運用に組み込むことで初めて機能します。
「Claude Codeがこの場面で違う判断をした」「ここの説明がブレた」というフィードバックを、SKILL.md側に書き足していきます。チームの誰でも編集できる場所に置くこと、変更履歴をレビューする時間を設けることがポイントです。
ここを軽く見ると、せっかく作ったSKILL.mdが古くなって誰も使わなくなる、という典型的な「ドキュメントが死ぬ」パターンに陥ります。
SKILL.md がチームにもたらす変化
SKILL.mdを運用に組み込めると、マネジメントの景色は地味に大きく変わります。
第一に、新人や中途入社者の立ち上がりが早くなります。これまで暗黙知として個人に張り付いていた「うちのやり方」が、SKILL.mdとして誰でも読める形になっているからです。Claude Codeに相談しながら立ち上がる、という新しい立ち上げ方も成立します。
第二に、マネージャーの「同じ説明地獄」が減ります。「この前提、何度言ったか分からない」という状態は、SKILL.mdとして一度ちゃんと書き切ることで終わらせられます。
第三に、ドキュメント整備の動機が変わります。これまで「ドキュメントは大事だがすぐリターンが見えない」と扱われがちだった整備業務が、「Claude Codeが即動く形にすれば、その日からチーム全員のスピードが上がる」という、わかりやすい投資対効果に変わります。
ここまで来ると、SKILL.mdの整備は単なるAI活用ではなく、ナレッジマネジメントそのものになっていることに気づきます。Claude Codeを組織に定着させる流れと、ドキュメント文化を強くする流れが、一本の線でつながっていきます。
なお、SKILL.mdを整備しても「現場で使われない」と悩むパターンには別の構造があります。Claude Code自体の社内浸透については、 Claude Code が社内で使われない3つの原因｜定着させる3段階フレーム を読むと、SKILL.mdの整備と現場への浸透を、セットで進めるイメージが湧きやすくなります。
まずは1枚から始める
SKILL.mdは、最初から完璧な体系を目指すと、ほぼ確実に頓挫します。
おすすめは、「毎週やっている同じ説明」を1つだけ選び、まず1枚のSKILL.mdを書いてみることです。1枚書いて使ってみると、「ここの粒度がズレていた」「この前提を書き忘れていた」が必ず見えます。それを直しながら、2枚目、3枚目と増やしていけば十分です。
マネージャーの立場で大事なのは、SKILL.mdを「個人の道具」で終わらせず、チームの資産として育てる文化を作ることです。レビューの時間を取り、誰が直してもよい場所に置き、使った人がフィードバックを書き戻す。これだけで、AI活用とドキュメント整備が同時に前に進みます。
「組織としてAIを使う」とは、結局のところ、暗黙知を再利用可能な形に書き直し続ける営みです。SKILL.mdは、その一番手前にあるシンプルで強力な道具だと言えます。
組織としてAIを入り口から扱いたいマネージャーには、テックエイドのAIX-101 / AIX-102をおすすめします。SKILL.mdのようなドキュメント整備とClaude Code活用を「組織で使うAI」の文脈でつなげて学べる構成になっており、この記事で扱った「業務標準をAIが動ける形で残す」考え方を、明日からの運用に落とし込みやすくなります。