EN|JA

DevGENT

テクノロジー

Claude Code Skillsの書き方｜公式と公開実例で設計

検索意図は「Claude CodeのSkills/SKILL.mdをどう書くか」。公式の配置と呼び出し、des…

krona23
37〜55分

Claude Code で同じ手順やチェックリストをチャットに貼り続けていると、会話は長くなり、チーム内の再現性も落ちます。一方で、有名な .claude/skills 公開パックをスター数だけで全部入れると、意図しない自動呼び出しやコマンド名衝突が起きやすくなります。

📑目次
  1. なぜ今「良い Skills の書き方」が実務論点になるか
  2. 公式が定める Skills の境界 — 配置・呼び出し・設定
  3. 公式ベストプラクティス — description・自由度・段階開示
  4. 公開実例の対照 — 日常結晶型 vs SDLCパック型
  5. 48時間でやる導入チェックリストと見送り条件
  6. よくある質問（FAQ）
  7. まとめと次アクション

本記事のゴールは、Claude Code Skills（SKILL.md）を「いつ切り出し、どう書き、どう評価して入れるか」を実務判断できる状態にすることです。

根拠は次の独立ソースに寄せます。

人気記事やブックマーク数は発見のきっかけに留め、数値や手順の一次根拠には使いません。

基礎の網羅が先に必要な場合は、Claude Code Skills 完全ガイド もあわせて参照してください。本記事は「公式境界 × 公開実例の対照 × 48時間チェックリスト」に絞ります。

なぜ今「良い Skills の書き方」が実務論点になるか

読者の痛みと discovery の差

結論から言うと、読者の痛みは「有名パックを知らないこと」ではなく、次の3点です。

  • 同じ手順のコピペ
  • CLAUDE.md の肥大
  • 自動で変な Skill が発火すること

公開ラッシュやスター数は discovery（発見シグナル）であり、設計品質の証明ではありません。

公式の作りどきと CLAUDE.md との差

Claude Code 公式は、同じ指示・チェックリスト・多段手順をチャットに貼り続けているとき、または CLAUDE.md の一節が「事実」ではなく「手続き」に育ったときに Skill を作る、と説明しています。

  • CLAUDE.md: 常時コンテキストに載る
  • Skill 本文: 使われたときだけロードされる

長い参照資料を Skill 側に逃がすと、未使用時のトークンコストを抑えられます。

カスタムコマンドとの関係と最初のゴール

また、従来の .claude/commands/ カスタムコマンドは動作を継続しつつ、Skills 側ではサポートファイル、呼び出し制御、自動ロードといった拡張が加わります。つまり Skills は「コマンドの置き換え」ではなく、「手続きを発見可能にし、必要なときだけ膨らませる」設計単位です。

読者への含意は明確です。最初のゴールは有名パックの全導入ではありません。自チームで週に何度も貼っている手順を1本、Skill 候補として切り出すことです。

公式が定める Skills の境界 — 配置・呼び出し・設定

Skill を書く前に固定すべきなのは、「どこに置き、誰が呼び、何を自動で許すか」です。本文の文章力より先に、この境界が運用事故を減らします。

配置階層

公式ドキュメントが示す主な配置は次のとおりです。

スコープ パス例 主な用途
Personal ~/.claude/skills/<name>/SKILL.md 全プロジェクト共通の個人手順
Project .claude/skills/<name>/SKILL.md リポジトリ規約・チーム手順
Plugin / Enterprise managed 管理配布 組織標準・統制された配布

同名が衝突した場合の優先度は enterprise > personal > project です。いずれかが bundled Skill を上書きできます。monorepo ではサブディレクトリの .claude/skills/ も使え、衝突時は apps/web:deploy のような qualified 名で区別します。

出典: Claude Code Skills（2026年7月時点）

呼び出しと frontmatter

呼び出しは主に2系統です。

  1. /skill-name による明示呼び出し
  2. description が会話内容と一致したときの model 自動ロード

副作用のある操作（deploy、commit、本番設定変更など）では、disable-model-invocation: true で user 専用にするのが公式パターンです。背景知識として持たせたいだけの Skill は user-invocable: false で / メニューから隠す選択もあります。

frontmatter の主な設計レバーは次です。

  • description
  • allowed-tools
  • paths
  • context: fork
  • hooks

さらに `!command`` 形式で、Skill ロード前にgit diff` などのコマンド出力を注入する動的コンテキストも使えます。

読者への含意: 副作用のある Skill は自動発火を止め、プロジェクト skill と personal skill の名前衝突を導入前に洗い出してください。名前が同じだと、想定と違う手順が先に勝ちます。

公式ベストプラクティス — description・自由度・段階開示

良い Skill は「長い説明文」ではありません。発見可能性とトークン経済の設計です。Platform 公式の best practices は、この点をかなり具体に書いています。

description が品質の入口

  • name: 最大64文字、小文字・数字・ハイフンのみ。予約語 claude / anthropic は不可
  • description: 空不可、最大1024文字。三人称で「何をするか」+「いつ使うか」
  • 曖昧表現の禁止例: “Helps with documents” / “Processes data” / “Does stuff with files”
  • 命名は gerund 形（例: processing-pdfs）を推奨。helper や utils は避ける

description は起動時にメタデータとして載りやすい一方、SKILL.md 本文は関連時のみです。つまり description が弱いと「必要なときに呼ばれない」、長すぎて手順を全部書くと「本文を読まずに済まされる」両方が起きます。

自由度（Degrees of freedom）

タスクの脆さに合わせて指示の固さを変えます。

  • High: コードレビューなど文脈依存で複数手法が妥当
  • Medium: テンプレート＋パラメータ
  • Low: migrate など順序固定・壊れやすい操作

自由度を誤ると、レビュー Skill が過剰に硬直したり、migrate Skill が途中で「工夫」して壊れたりします。

Progressive disclosure（段階開示）

  • SKILL.md 本文は 500行以内 が最適
  • 詳細は別ファイルへ分割し、参照は1階層まで
  • 目次・概要を SKILL.md、詳細・スクリプト・例はオンデマンド

出典: Skill authoring best practices（2026年7月時点）

テストも公式チェックリストに含まれます。使う予定のモデル（Haiku / Sonnet / Opus）で検証し、次を確認します。

  • description のトリガー語
  • 500行制限
  • 用語一貫
  • 具体例
  • 1階層参照
  • 依存パッケージの仮定禁止
  • 重大操作の検証ステップ
  • 少なくとも複数の eval
  • 実利用シナリオ

読者への含意: description を先に書き、本文は目次と必要分岐だけに絞る。詳細は「全部載せ」ではなく「必要な枝だけ読む」設計にしてください。

公開実例の対照 — 日常結晶型 vs SDLCパック型

同じ「公開 .claude/skills」でも、設計思想は大きく違います。両方をルーターとして同時全面導入しないことが、実務上の安全策です。

公開パックは検証環境で1本から小さく始め、呼び出し結果を確認できるまで導入範囲を限定してください。

観点 日常結晶型（mattpocock/skills 系） SDLCパック型（addyosmani/agent-skills 系）
主眼 1人の実運用フローの結晶 Define〜Ship を Skill 群でカバー
呼び出し設計 user-invoked / model-invoked の分離が明示 多数スキル＋評価基盤で発火精度を測る
代表メタ writing-great-skills / grilling 等 Common Rationalizations・Red Flags・Verification 型
成長の見せ方 deprecated / in-progress を公開 eval cases・CI deterministic tier
導入リスク 哲学の強い個別スキルを無選別で増やす 他パックとコマンド名衝突・二重ルーター

出典: mattpocock/skills、addyosmani/agent-skills（2026年7月時点の公開ページ観察）

日常結晶型（mattpocock/skills 系）

mattpocock/skills は “Skills for Real Engineers. Straight from my .claude directory.” と掲げ、日常フローから切り出した実物が中心です。

特徴は次のとおりです。

  • user-invoked と model-invoked の分離
  • writing-great-skills のようなメタ Skill
  • deprecated / in-progress の可視化

SDLCパック型（addyosmani/agent-skills 系）

addyosmani/agent-skills は “Production-grade engineering skills for AI coding agents.” の方向です。

目立つ要素は次のとおりです。

  • Claude / Codex / OpenCode 等へのレイアウト
  • evals（trigger ranking、catalog collision 等）
  • Common Rationalizations（よくある言い訳）
  • Verification チェックリスト

Addy Osmani 系パックの導入判断そのものを深掘りした関連記事として、Agent Skills 公開解説 も参照できます。

共通して効く書き方

公開ページ上のスター数は変動する発見シグナルであり、優劣や安全性の根拠にはしません。共通して効く書き方は次の4点です。

  1. description で勝負する
  2. SKILL.md に全部書かない
  3. 呼び出し（user / model）を意図的に決める
  4. 手抜き経路（合理化・未検証）を塞ぐ

読者への含意: まず自ワークフローに近い1本の SKILL.md を読み、既存 skill 名を確認してからつまみ食いしてください。

48時間でやる導入チェックリストと見送り条件

ここまでの論点を、48時間以内に実行できるチケットに落とします。成功指標は「Skill の本数」ではなく、意図したときだけ発火し、手順が再現することです。

チェックリスト

  1. 候補選定: 週2回以上貼っている手順、または CLAUDE.md の手続き節を1つ選ぶ
  2. 置き場: 個人共通なら personal、リポジトリ規約なら project .claude/skills/<name>/
  3. description: 三人称で what + when。曖昧な3例（documents / data / files だけ）を避ける
  4. 呼び出し: 副作用あり → disable-model-invocation: true。探索補助 → model-invoked を検討
  5. 本文: 500行以内。分岐の一部だけ必要な情報は参照ファイルへ（1階層）
  6. 検証: /name 明示と自然文トリガーの両方で試し、使うモデルで追加指示の要否を確認
  7. 公開パック: 入れるなら信頼ソース確認 → SKILL.md / scripts を読む → 1本だけ
  8. 衝突回避: 既存 skill 名と二重ルーターを避ける。2系統パックの同時全面導入は見送り候補

公開パック導入前のセキュリティ確認

Anthropic Engineering は、Skills が手順・参照・スクリプトをバンドルし得ること、信頼できないソースからの導入がデータ窃取や環境侵害につながり得ることを警告しています。有名リポジトリでも、次を確認してから入れてください。

  1. 作者・配布元が組織ポリシー上信頼できるか
  2. allowed-tools / shell 実行 / 外部通信の範囲
  3. スクリプトが最小権限で、秘密情報を外へ出さないか
  4. project と personal の同名衝突
  5. 初回は1スキルずつ入れ、意図しない自動呼び出しがないか観察

出典: Equipping agents with Agent Skills（2026年7月時点）

見送り条件

  • SKILL.md を読まずスター数だけで入れる
  • デプロイ系を model 自動呼び出しのままにする
  • 説明が曖昧で発火条件が分からない
  • 同名 skill が既にあり、上書き影響を評価していない

48時間の終わりには、読者が48時間以内に、(a) 繰り返し手順を1つ選んで Skill 候補にし、(b) description に what+when を書き、(c) user-invoked か model-invoked を決め、(d) 公開パックを入れるなら SKILL.md を読んで1本だけ試す、という手順を取れる状態を目指してください。公開パックの本格検討はその後です。

関連記事:

よくある質問（FAQ）

CLAUDE.md に全部書けば Skills は不要か？

常時ロードの手続きが増えると、コンテキスト圧迫とノイズが増えます。手続き化した節は Skill に切り出すのが公式の作りどきです（Claude Code Skills）。

description に手順の要約を長く書いてよいか？

what + when は必須ですが、手順の丸写しは本文未読で済まされるリスクがあります。詳細は SKILL.md 本文と1階層の参照ファイルへ寄せます（best practices）。

有名 GitHub の skills を丸ごと入れてよいか？

信頼ソース確認と中身レビューが前提です。複数パックの同時ルーター化はコマンド衝突・哲学混線のリスクがあります。1本ずつ入れ、観察してください（Anthropic Engineering）。

user-invoked と model-invoked はどう使い分けるか？

副作用・不可逆操作は user 明示（disable-model-invocation）。探索・補助は description 駆動の自動呼び出しを検討します（Claude Code Skills）。

まとめと次アクション

要点は3つです。

  1. Skills は CLAUDE.md の手続き肥大を逃がし、必要なときだけ手順をロードする公式機能である
  2. 品質の骨格は description（what+when）、自由度、500行/1階層の段階開示である
  3. 公開実例は対照教材として使い、導入はセキュリティ確認と衝突回避付きで1本ずつ行う

読者が48時間以内に取れる次アクションは、次の4点です。

  1. (a) 繰り返し手順を1つ選んで Skill 候補にする（週2回以上貼っている手順、または CLAUDE.md の手続き節）
  2. (b) description に what+when を書く（三人称・曖昧な documents/data/files 表現は避ける）
  3. (c) user-invoked か model-invoked を決める（副作用ありなら disable-model-invocation: true）
  4. (d) 公開パックを入れるなら SKILL.md を読んで1本だけ試す（信頼ソース確認と衝突回避の後）

チェックリスト1〜6で (a)〜(c) と明示呼び出し /name の成功まで進め、その後に (d) を検討してください。まず自作 Skill 1本から小さく始め、意図したときだけ発火し手順が再現できるまで導入範囲を限定します。

基礎の設定・運用を広げたい場合は Claude Code Skills 完全ガイド を、SDLC パック型の導入判断を深めたい場合は Agent Skills 公開解説 を続けて読むとよいです。

関連する新しい記事:

新しい関連情報:

📖 この記事で紹介した関連記事

krona23

著者

krona23

IT業界20年以上の実務経験を持ち、日本国内有数のPVを誇る大規模Webサービスで事業部長・CTOを複数社で歴任。Windows/iOS/Android/Webと技術の変遷を経験し、現在はAIネイティブへの変革に注力。DevGENTでは、AIコードエディタ・自動化ツール・LLMの実践的な使い方を日英西3言語で発信中。

DevGENT について →

📚 次に読む

← 前の記事GPT-5.6 Sol トークン使用量とAPI料金の見積もり【2026】次の記事 →Claude Codeのハーネスとは｜モデル・内部ループ・外部設定の3層

🔥 よく読まれている記事

  1. GPT-5.5 Codex から GPT-5.6 へ｜ChatGPT統合・Sol/Terra/Luna・10倍終了後の料金【2026年7月更新】
  2. 二段階式フィッシングメールの手口と見抜き方 2026年最新対策
  3. 低VRAMでOpus級性能のオープンソースAI GLM-5.2とGemma 4 12B Coder徹底解説
  4. LM Studio Bionic 初期プレビュー｜文書とコードの進め方
  5. Anthropic公式が整理するAIコーディングの4種類のループ 停止条件と実務活用ガイド

コメントを残す

Trending

DevGENTをもっと見る

今すぐ購読し、続きを読んで、すべてのアーカイブにアクセスしましょう。

続きを読む