Claude Code Skills の作り方【2026年版】｜SKILL.md の書き方と社内展開・運用ガイド

Claude Code Skills（Agent Skills）とは、SKILL.md という1枚の Markdown ファイルに業務手順を書くだけで、Claude Code に新しい能力を後付けできる Anthropic 公式の拡張機能です。関数呼び出しのような複雑な実装は不要で、YAML frontmatter + Markdown 本文を書いて所定のフォルダに置くだけで、Claude が「いつ使うか」を自律的に判断して呼び出します。

本記事を読むと、以下の3点がわかります。

• SKILL.md の正しい書き方（YAML frontmatter + Markdown 本文）と配置場所
• 社内で使い回せる Skill を作る手順と、既存 Skill 一覧の探し方・再利用方法
• 権限設計・社内展開・長期運用でつまずかないための注意点

より広く「Claude Skills とは何か・Projects との違い」を知りたい方は、別記事のClaude Skills とは？繰り返し業務を社内で仕組み化する活用ガイドも参考にしてください。本記事は SKILL.md を実際に書く・配置する・運用する、より実装寄りの内容にフォーカスします。

SKILL.md の正しい書き方｜YAML frontmatter + Markdown 本文

SKILL.md は YAML frontmatter と Markdown 本文の 2 部構成です。JSON で関数定義を書く形式ではありません。古い記事や AI が生成したサンプルで { "name": "...", "parameters": {...} } のような JSON が出てきたら、それは Function Calling と混同した古い説明なので無視してください。

最小サンプル（Anthropic 公式仕様）

公式ドキュメントの最小例を、業務向けに書き直したのが下記です。~/.claude/skills/summarize-changes/SKILL.md として保存します。

---
description: 直近のコミット差分を 3 行で要約し、レビュー必須箇所を指摘する。「何を変えた？」「コミットメッセージ作って」と聞かれたときに使う。
---

## Current changes

!`git diff HEAD`

## Instructions

上記の差分を 2〜3 個の箇条書きで要約したあと、エラーハンドリング不足・ハードコード値・テスト追加が必要な箇所など、レビュアーが見るべきリスクを列挙してください。差分が空なら「未コミットの変更はありません」と返してください。

ポイントは 3 つです。

1. YAML frontmatter は --- で囲む。description フィールドが、Claude が「いつこの Skill を呼ぶか」を決める鍵
2. !`コマンド`（バッククオート開始のシェル実行） で、Skill 起動時にコマンド出力を本文へ動的注入できる
3. 本文は普通の日本語でも英語でも OK。Claude が読んで実行する手順書なので、自然言語で書ける

frontmatter で指定できる主な項目

description の書き方が Skill の発火率を決めます。「いつ使う」を具体的なトリガー語で書くのがコツです。「コミットメッセージ作って」「差分レビューして」のように、ユーザーが実際に発する言葉を入れましょう。

Skill の配置場所

Skill は配置場所で利用範囲が決まります。

社内で複数人が使う Skill は .claude/skills/ に置いて git にコミットすると、リポジトリを clone するだけで全員が同じ手順を使えるようになります。個人の作業効率化用途は ~/.claude/skills/ に置くのが基本です。

どんな業務を Skill 化すべきか｜判断ポイントと社内展開の作り方

どんな業務を Skill 化すべきかは、以下の 3 つで判断します。

1. 同じ手順を 3 回以上繰り返している — チャットへ毎回貼り付けている指示は、Skill 化の最有力候補
2. CLAUDE.md に書きすぎてファクトより手順が増えてきた — 手順は Skill 側へ切り出すと CLAUDE.md が軽くなる
3. 誰かに引き継ぎたい — Skill は git で共有でき、属人化を解消できる

これは公式ドキュメント Extend Claude with skills でも推奨されている判断軸で、「同じ指示を毎回貼り付けるなら Skill にしよう」というシンプルな基準です。

社内展開の進め方

1 人で作った Skill を社内標準にするステップは次の通りです。

1. 個人の ~/.claude/skills/ で試作し、実運用で 2〜3 回動かして安定を確認する
2. .claude/skills/ へ移してリポジトリにコミットする（プロジェクト単位で共有）
3. PR レビューに Skill 自体も含める（許可ツールが広すぎないか・description が曖昧でないかをチェック）
4. チームに「この Skill があること」を周知する（Slack・Wiki・オンボーディング資料に一覧を掲載）

Skill は増えるほど「どれがどこにあるか分からない」状態になりがちです。プロジェクトの CLAUDE.md に Skill 一覧の索引を持たせておくと、後から参加したメンバーでも迷わず使えます。

既存 Skill の探し方・再利用方法

ゼロから書くより、既存の Skill を流用する方が圧倒的に速いケースが多いです。2026 年時点で活用しやすい配布元は以下の 3 つです。

主要レジストリ・配布元

外部から取得した Skill は、必ず SKILL.md の中身を目視確認してから本番運用してください。allowed-tools で許可されているツールが想定外に広い Skill は、勝手にネットワーク経由でファイルを送信する余地があります。

自作 Skill のベストプラクティス

公式ドキュメントが推奨する 3 つの設計指針は次のとおりです。

1. SKILL.md は 500 行以内に収める — 詳細は references/api-spec.md のように別ファイルへ分離する
2. description にトリガー語を 3〜5 個入れる — 「コミットメッセージ作って」「diff 要約」など、ユーザーが実際に発する表現を列挙
3. 副作用がある Skill は disable-model-invocation: true — /deploy /send-email などは Claude が勝手に発火しないようにする

応用編：チャットツール連携で Skill を業務オペレーションに広げる

Claude Code の Skill は開発端末での利用が基本ですが、SKILL.md は Agent Skills オープン標準（agentskills.io）に沿って作られているため、同じファイルをチャットツール経由の業務オペレーションに転用する動きも出てきています。代表例が OSS の自律エージェント基盤「OpenClaw」です。

OpenClaw は Telegram / Discord / LINE などのチャットから PC を遠隔操作し、Cron 実行や Webhook 受信で定期タスクを回せる基盤です。OpenClaw 公式ドキュメントでは「Claude Code バックエンドの場合、OpenClaw は適格スキルを Claude Code のネイティブスキルリゾルバーに渡す」と明記されており、Claude Code 用に書いた SKILL.md がそのまま OpenClaw でも動きます。

責務分離の考え方

Claude Code と OpenClaw を併用する場合は、以下のように役割を分けるのが実務上のセオリーです。

「コードを書く」は Claude Code、「定期的に・チャット経由で・PC を動かす」は OpenClaw、と覚えると失敗しません。OpenClaw の基本的な使い方や環境構築を先に知りたい方は、別記事のOpenClawとは？非エンジニア向けの使い方・できること・環境構築ガイドを参照してください。

導入手順としては、~/.claude/skills/weekly-report/SKILL.md に週次レポート手順を書き、OpenClaw の Cron で「金曜 17 時に /weekly-report を実行」と設定すれば、レポート生成は Claude Code が担い、配信は OpenClaw が Slack/Telegram へ流す、という構成が組めます。法人で本格運用する際の料金プランは、別記事のClaude Code 法人利用ガイド｜最適な料金プランと安全な契約手順に詳しくまとめています。

セキュリティとガバナンス｜権限の境界線を引く

Skill は強力な反面、allowed-tools で広い権限を与えると、悪意あるプロンプトインジェクションで機密情報が外部へ送られるリスクがあります。以下の 3 層の防御を、Skill を 1 つ追加するたびに必ず実施してください。

1. allowed-tools を最小限に絞る

allowed-tools: Bash(*) のように全 Bash を許可するのは厳禁です。Bash(git diff *) Bash(git log *) のように、コマンドの prefix まで限定して書きます。書き込み系・送信系（Bash(rm *), Bash(curl -X POST *) など）は別 Skill に分離し、disable-model-invocation: true でユーザー承認必須にします。

2. サンドボックス + 専用ディレクトリ

ファイルアクセスはホームディレクトリ全体ではなく、~/work/agent-sandbox/ のような専用フォルダだけに絞るのが推奨です。チャットツール経由で PC を操作する構成（OpenClaw 等）を組み合わせる場合は、より厳密な隔離が必要になります。別記事のOpenClaw を Docker × Mac で構築する法人向けセキュリティ対策にも隔離の考え方をまとめています。

3. ヒューマン・イン・ザ・ループ（HITL）

メール送信・支払い処理・データ削除など「取り消し不能」な操作は、Skill 単独で完結させず、必ずユーザー承認を挟みます。Claude Code は disable-model-invocation: true で実装できます。

シャドー AI（社員が無断で自動化スクリプトを動かす）の防止策は、より広い視点でAI ガバナンスとは？企業向けガイドラインと 6 つの手順も参考にしてください。AI リスクアセスメントの全体像を押さえたい方はAI リスクマネジメント実践ガイドが役立ちます。

長期運用のメンテナンス指針

Skill は一度作って終わりではなく、API 仕様変更や業務フロー改定で陳腐化します。3 つの運用ポイントを押さえると保守性が大きく上がります。

1. Skill は git で版管理する

.claude/skills/ をプロジェクトリポジトリに含め、レビュー対象に組み込みます。コードと同じく PR レビューで「許可ツールが広すぎないか」「description が曖昧でないか」をチェックする運用が現実的です。

2. 単一責任原則を守る

1 つの Skill に複数の業務を詰め込まず、commit-message / pr-summary / weekly-report のように 1 Skill = 1 タスクで切り分けます。トラブル時の原因特定が容易になり、Skill 同士の組み合わせで複雑な業務フローを構築できます。

3. 実行ログを残す

${CLAUDE_SESSION_ID} を使って logs/ 以下に実行履歴を吐き出す Skill を 1 つ用意し、他 Skill から呼び出す構成にすると、後追い監査が可能になります。

よくある質問（FAQ）

Q1. SKILL.md は JSON で書くのですか？

いいえ。SKILL.md は YAML frontmatter + Markdown 本文です。{ "name": "...", "parameters": {...} } のような JSON で書く形式は OpenAI 系の Function Calling と混同した古い情報なので、参考にしないでください。Anthropic 公式仕様では Markdown ファイル 1 枚です。

Q2. Skill が自動起動しないときは？

description フィールドにユーザーが発する自然な言葉が入っているか確認してください。トリガー語が少ないと Claude が Skill の存在に気づかないことが多いため、トリガー語を 3〜5 個入れるのが定石です。それでも起動しない場合は /skill-name で明示的に呼び出します。

Q3. Claude Code 用の Skill を他のツールでも使えますか？

SKILL.md は Agent Skills 標準（agentskills.io）に沿って作られているため、同じ標準をサポートするツール（OpenClaw 等）であれば、書き直さずにそのまま使えます。

Q4. 外部から取得した Skill は安全ですか？

そのまま使わず、必ず SKILL.md の中身を目視確認してください。allowed-tools が広すぎる Skill や、!`curl ...` で外部にデータを送る Skill は、本番投入前に書き換えるか却下する必要があります。

Q5. 月額料金はいくらかかりますか？

Skill 自体は無料です。Claude Code は Anthropic API の従量課金または Claude Pro / Team / Enterprise プランの範囲で動きます。費用感の比較はClaude Code 法人利用ガイド、最新モデルとプラン全体はClaude 最新モデル選び方ガイドを参照してください。

まとめ：SKILL.md 1 枚から業務の仕組み化を始める

Claude Code Skills は、SKILL.md という 1 枚の Markdown ファイルに手順を書くだけで、Claude に新しい能力を後付けできる仕組みです。関数定義のような複雑な実装は不要で、YAML frontmatter と自然言語の本文だけで、社内の繰り返し業務を仕組み化できます。

導入を成功させる 3 つのポイントは以下のとおりです。

• 書き方は YAML frontmatter + Markdown（JSON ではない）。description にトリガー語を 3〜5 個入れる
• 配置場所を使い分ける：個人利用は ~/.claude/skills/、チーム共有は .claude/skills/ に git コミット
• 権限最小化 + HITL + ログ取得を Skill 1 つ追加するたびに必ず設計する

まずは「毎日繰り返している指示」を 1 つだけ Skill 化し、~/.claude/skills/ に置いてみてください。それが Claude Code Skills を業務に定着させる、最も確実な第一歩になります。