まず結論
your-project/
├── .claude/
│ └── skills/
│ └── incident-report/
│ ├── SKILL.md
│ └── references/
└── src/
Codex も併用しているなら .agents/skills/ にも同じものを置きます。置き場所の違いは導入ガイドに対比でまとめています。
理由は 3 つ
git pullで全員に届く配布の仕組みを別に作らなくて済む- 変更の履歴が残る誰がいつ何を変えたかが追える
- レビューを通せるプルリクエストの仕組みがそのまま使える
個人環境への配布は勧めません
逆に、個人環境（~/.claude/skills/）への配布は勧めません。入れる作業が各自の手作業になり、誰がどの版を持っているか分からなくなります。
プロジェクトと個人の使い分け
プロジェクト（.claude/skills） | 個人（~/.claude/skills） | |
|---|---|---|
| 共有 | git で全員に届く | 各自が手で入れる |
| 版の管理 | リポジトリの履歴 | 把握できない |
| 向くもの | チームの作法、業務の手順 | 個人の好み、探索用の道具 |
| 影響範囲 | このプロジェクトだけ | すべてのプロジェクト |
業務の手順はプロジェクト側に
業務の手順はプロジェクト側に置いてください。「障害報告書の書式」「このサービスの設計の進め方」はプロジェクトに紐づく知識です。
個人側に置くのは、どこでも使う道具だけ
個人側に置くのは、find-skills のようなどのプロジェクトでも使う道具に限ります。
-g を付けると共有されない
注意: npx skills add に -g を付けると個人環境に入ります。社内配布のつもりで -g を使うと、その人の端末にだけ入って共有されません。
同じ名前なら個人側が勝つ
Claude Code では、同じ名前のスキルが両方にあると個人側が優先されます（公式ドキュメント、2026-10-09 確認）。誰かが個人環境に同名の古い版を持っていると、プロジェクトの版は使われません。「自分だけ挙動が違う」と言われたら、~/.claude/skills/ に同名が無いかを見てください。
フォルダごと置く
SKILL.md だけをコピーしてはいけません
参照資料やスクリプトを使うスキルは、それらが無いと動きません。
実データで
azure-prepare は同梱ファイル 165 件、skill-creator は 17 件（うち実行可能な Python が 10 件）を持っています（2026-10-09 確認）。SKILL.md は入口で、本体は周りのファイルです。
シンボリックリンクは勧めません
.claude/skills/x を別の場所へのリンクにする運用はできますが、リンク先がリポジトリの外にあると、他の人の環境で壊れます。実体を置いてください。
npx skills add は既定で、実体を .agents/skills/ に置いてリンクを張ります（2026-10-09 確認）。プロジェクトに入れた場合はリンク先もリポジトリの中なので、両方をコミットすれば届きます。リンクを避けたいなら --copy で実体をコピーできます。
レビューの観点
スキルはプロンプトに差し込まれる文章で、コードと同じくらい挙動を変えます。プルリクエストで見るべき点を挙げます。
nameがフォルダ名と一致しているか仕様の制約。検証ツールで機械的に確かめられるdescriptionが呼び出しの条件になっているか「何をするか」と「いつ使うか」の両方- 破壊的な操作が入っていないか削除・履歴の書き換え・本番への接続
allowed-toolsに何が並んでいるか確認なしで使える道具の宣言。最小限か- 秘密情報が書かれていないかAPI キー・接続文字列・社内のホスト名
1. name がフォルダ名と一致しているか
仕様では、name は小文字・数字・ハイフンだけで、フォルダ名と一致させる決まりです。Claude Code は一致していなくても読み込みますが、ほかの実行環境や検証ツールでは落ちます（2026-10-09 確認）。
仕様の検証ツール skills-ref validate <フォルダ> を、プルリクエストの確認に入れておくと機械的に止められます。
2. description が呼び出しの条件になっているか
紹介文になっていないか確認してください。「何をするか」と「いつ使うか」の両方が必要です。
似た既存のスキルと条件がかぶっていないかも見ます。かぶると、どちらが呼ばれるか安定しません。書き方はSKILL.md の書き方にまとめています。
3. 破壊的な操作が入っていないか
ファイルの削除、git の履歴を書き換える操作、本番環境への接続。入っているなら、利用者に確認を取る指示が併記されているかを見ます。
参考になる書き方が実データにあります。azure-prepare の本文には「ユーザーのプロジェクトやワークスペースのディレクトリを絶対に削除しない」「破壊的な操作は必ず利用者に確認する」と明記されています。
4. allowed-tools に何が並んでいるか
allowed-tools は道具を絞る項目ではありません。Claude Code では、並べた道具をそのスキルを呼んだ回だけ確認なしで使えるようにする宣言です（事前承認）。ほかの道具も使えるままです（公式ドキュメント、2026-10-09 確認）。
当サイトの収録 470 件中、使っているのは 64 件（約 14%、2026-09-18 時点）。
allowed-tools: Read, Grep
この例なら、読むだけの道具を確認なしで使う宣言です。並んでいるものが最小限かを見てください。Bash がそのまま入っていたら、シェルの実行が確認なしで通ります。
道具を使えなくしたいなら、別の項目 disallowed-tools（Claude Code の拡張）を使います。
5. 秘密情報が書かれていないか
API キー、接続文字列、社内のホスト名。スキルはリポジトリに入るので、コードと同じ扱いが必要です。環境変数から読む形にしてください。
更新の伝え方
現実的な方法は 2 つです。
1. 変更履歴を同梱する
incident-report/
├── SKILL.md
└── CHANGELOG.md
2. metadata に版を入れる
metadata:
version: "1.2.0"
author: platform-team
metadata.versionを使っている（470 件中、2026-09-18 時点）- 136 件
- 最上位に
version:と書いている（仕様にない項目） - 51 件
実データでは、最上位に version: と書いている 51 件は仕様にない項目です。Claude Code は黙って無視し、仕様の検証ツールはエラーにします。metadata の中に入れてください。
挙動が変わる更新は周知する
挙動が変わる更新は、周知したほうがいいです。「今日からレビューの指摘が厳しくなった」は、知らされていないと不具合に見えます。
外部のスキルを取り込むとき
公開されているスキルをそのまま .claude/skills/ に入れるかどうかは、判断が分かれます。
そのまま入れる
更新は自分たちで追う必要があります。取り込んだ時点で分岐し、原本が変わっても自動では入りません。中身は固定されるので、挙動が勝手に変わりません
社内配布ならこちら
npx skills add で各自に入れさせる
版が人によってばらつきます。更新は各自のタイミングになります
入れる前に中身を読む
取り込むときは、入れる前に中身を読んでください。何を確認すべきかはスキルを入れる前に確認することにまとめています。
よくある質問
部署ごとに違うスキルを使いたいときは
プロジェクトごとに置けば自然に分かれます。.claude/skills はそのプロジェクトの中だけで有効です。
複数のプロジェクトで共有したいものは、社内のテンプレートリポジトリに置いて、各プロジェクトへコピーする形が現実的です。
スキルの数が増えてきたら
似た説明文のスキルを並べないでください。エージェントは説明を読んで呼ぶかを決めるので、用途がかぶるスキルが複数あると、どれが呼ばれるか安定しません。
使われていないスキルは外してください。「入れておけば役に立つかも」という理由で残すと、判定を邪魔する側に回ります。
自作スキルが効いているかを確かめる方法は
スキル無しでどう外すかを先に見てください。writing-skills の中心はこれです。
スキル無しで同じ依頼をしてみて、期待と違う結果が出ることを確認してから書く。そうしないと「エージェントが既にできていること」を書いてしまい、入れても行動が変わりません。
定量的に見たいなら skill-creator にお題を走らせて結果を並べる仕組みがあります。
スキルをレビューできる人がいません
まず description と、破壊的な操作の有無だけを見てください。この 2 つで、事故の大半は防げます。
中身の妥当性の判断は、実際に使ってみてからでも間に合います。影響範囲の小さい依頼で試す手順はスキルを入れる前に確認することに書いています。