Claude Skills in Practice Claude Skills 実践ガイド

The Complete Guide to Building Skills for Claude

開発者とチームのための、段階を追った手引き。
SOP と専門知識を、自動化された仕事の流れに変えるまで。

まず概念：Skill とは何か

Skill は指示と手順を収めたフォルダです。会話のたびに背景を説明し直さなくても、あなた固有の進め方を Claude に正確に持たせられます。

標準的な Skill フォルダの中身：

  • SKILL.md（必須）中心となる指示。いつ起動するかを決める YAML の前書きを含みます。
  • scripts/（任意）実行できる自動化スクリプト（Python、Bash など）。
  • references/（任意）Claude が必要に応じて読む参考資料と手引き。

効くところ：一度教えれば、そのあとずっと効きます。チームの成果物の形もそろいます。

段階を追った開発の道すじ（The Staircase）

Step 1. 用途と場面を決める

使いどころをはっきりさせ、起動の条件と目標を決め、外部ツール（MCP）が要るかを見ます。

Step 2. 骨組みをつくる

フォルダをつくり、必須の SKILL.md を置き、kebab-case の命名を厳密に守ります。

Step 3. 指示を書く

YAML の起動語を正確に決め、段階的に開く原則にしたがって Markdown の指示を書きます。

Step 4. 試して配る

まず単一の仕事を手で試し、API と挙動に問題がないことを確かめてから ZIP にまとめてチームへ配ります。

MCP と Skills の組み合わせ

The Connectivity
MCP
外とつながる力
(What Claude can do)

道具に魂を入れる、その頭脳

MCP（Model Context Protocol）が外とつながる「手足」——Notion を読む、Linear に課題を立てる——だとすれば、Skills はその道具をどう正しく使うかを教える「頭脳」です。

Skill のない MCP：道具箱を前にどこから手をつけるかわからず、毎回込み入った指示を書き直すことになります。

Skill のある MCP：既定の流れがひとりでに立ち上がり、定石がやり取りのたびに埋め込まれます。覚えることが減ります。

よくある三つの使いどころ（Use Cases）

1. 文書と成果物の生成

形と質のそろった成果物をつくるとき。ブランドの指針、テンプレートの構造、公開前のチェックリストを埋め込めます。（外部ツールは不要）

2. 仕事の流れの自動化

手数の多い流れに向きます。Claude に順を追って進めさせ、確認の仕組みも組み込めます。複数の MCP サーバをまとめることが多くなります。

3. MCP を補強する

すでにある MCP サーバの補強に。領域の知識を入れ（Sentry でバグを自動で読み解くなど）、文脈を自動で足し、よくある API の間違いを先に防ぎます。

YAML の書き方：ここで生き死にが決まる

命名の決まり（Naming）

Claude はフォルダ名とファイル名の形にとても厳しく、わずかな違いで Skill が読み込まれません。

  • 主たるファイル名は正確にSKILL.md（大文字小文字を区別します。skill.md ではいけません）
  • フォルダとname:の項目には次を使いますkebab-case。
  • 厳禁空白、大文字、下線を含めないこと（例：Notion_Setupは誤りです）
  • 置かないこと：README.mdを Skill の直下に

説明と起動語（Description）

Description は Claude が自分から Skill を起動するかを判断する唯一の根拠です。1024 文字未満に収めます。

  • 両方を必ず書きます：「何ができるか」と「いつ使うか」（具体的な起動語）
  • 例：「デザイン原稿を読み解くときに使う。利用者が fig ファイルを上げたとき、または『デザイン仕様』を求めたとき。」
  • セキュリティ上の禁止：YAML の中で XML タグ< >を使わないこと。プロンプトインジェクションを防ぐためです。

指示の書き方、定石（Best Practices）

具体的で、実行できること

漠然とした指示は避けます。「データをきちんと検証する」ではなく、こう書きます。「scripts/validate.pyを実行し、エラーが出たら必須項目の抜けを確かめる。」コードは言葉より曖昧さがありません。

段階的に開く

トークンを使いすぎないために、SKILL.mdは中心の手順だけに絞ります。細かい API 仕様や大きなひな形はreferences/フォルダへ移し、Claude が必要になったときに読みにいく形にします。

あらかじめエラーに備える

起こりうるエラーを見越して、直し方まで書いておきます。たとえば「よくある不具合」の節を設け、「接続を拒否されたら、設定 > 拡張機能から接続し直してください。」人が入る回数がはっきり減ります。

実例その一：コードレビューの相棒

単一の仕事の、標準的な形

外部の MCP を使わない標準的なSKILL.mdの書き方です。要は、はっきりした前提条件とと、うっかりを防ぐ仕掛け。

  • YAML の部分：起動の条件を正確に決める。
  • Role（役割）：Claude に専門家の視点を渡す。
  • Workflow（手順）：番号で順序を強制する。
  • Rules（してはいけないこと）：「やらないこと」を明示し、踏み込みすぎを防ぐ。
---
name: strict-pr-reviewer
description: 利用者がコード片を上げたとき、またはコードレビューを求めたときに起動する。
---

# Role
あなたは厳しく、経験を積んだバックエンドの設計者です。

# Workflow
起動したら、次の手順を順番どおりに実行してください：
1. **セキュリティの確認**：SQL インジェクションや、書き込まれたままのパスワードがないか見る。
2. **性能の評価**：計算量が O(N^2) を超える書き方を指摘する。
3. **報告を出す**：修正案を Markdown の表で示す。

# Rules
- 書き直した完全なコードを**渡さないこと**。
- 具体的な直し方と考え方だけを示すこと。

実例その二：MCP につなぐ自動化

---
name: linear-bug-reporter
description: 会話の中のエラーログを、そのまま Linear の課題にする。
---

# Objective
エラーログを読み解き、`linear` の MCP を自分から使ってバグ票を立てる。

# Instructions
1. 利用者の Error Log から取り出す：コード、時刻、考えられる原因。
2. `linear_create_issue` を自分で呼ぶ。
3. Title は `[Bug] {エラーコード}` の形にする。

# Error Handling (Fallbacks)
- `linear` が見つからない、または接続できないとき、**謝らないこと**。
- そのまま切り替える：Markdown のバグ報告を出し、利用者に手で写してもらう。

手数の多い流れと、失敗したときの逃げ道

Claude を RPA のように外部 API を呼ばせつつ、自分で立て直す筋道まで持たせる例です。

  • Objective（目的）：この手順が最後に何を成すのかを一文で。
  • ツールを呼ぶ指示：呼ぶツールの名前をはっきり書く（例：linear_create_issue)。
  • Fallback（逃げ道）：ここが要です。MCP は切れるものと考え、ツールが使えないときに文章での出力へ切り替える方法を Claude に伝えておきます。流れが途中で止まらなくなります。

試して確かめる段階

「まず単一の仕事で Claude が完璧にこなせることを確かめ、そのうまくいった形を取り出して Skill に固める。」

試し方の全体像：三つの観点

観点 確かめたいこと 測り方（Metrics）
起動の確認（Triggering） 必要な場面できちんと読み込まれ、関係のない話では出しゃばらないこと。 関連する依頼の 90% で自動的に起動する（手で呼ばなくてよい）。関係のない指示では黙っている。
挙動の確認（Functional） 手順が思ったとおりの結果を出し、端の場合もきちんと扱えること。 未処理の API エラーがゼロ。ツールの呼び出しがすべて成功する。出力の形がそろっている。
効きの比較（Performance） Skill を入れたあとの流れが、人が手で導いていたときより効率がよいと示すこと。 やり取りの往復が大きく減る。使うトークンが減る。利用者が直しに入らずに済む。

一歩進んだ設計：五つの型

  • 順に並べる（Sequential Workflow）：手順 1 から手順 N までを厳密に決めます。前後の依存がある仕事に向きます。たとえば「顧客を登録する → 支払いを設定する → 歓迎のメールを送る」。
  • 複数の MCP をまたぐ（Multi-MCP）：サービスをまたいで組み立てます。Figma から書き出し（MCP 1）、Google Drive に保存し（MCP 2）、Linear に課題を立てる（MCP 3）。
  • 繰り返して整える（Iterative Refinement）：「下書きを出す → スクリプトで検証する → 自動で直す」という閉じた輪をつくり、質が届くまで終わらせません。
  • 文脈で分ける（Context-aware）：Claude に判断の木を渡します。「10MB を超えるファイルならクラウドストレージの MCP、コードなら GitHub の MCP。」
  • 領域の知識を入れる（Domain-specific）：API を呼ぶ前に、規程の確認やリスクの判断を挟みます。経験を積んだ専門家のようにふるまわせるためです。

最後の一歩：まとめて配る

まとめ方と入れ方：試し終えたら、フォルダを.zipにまとめます。個人なら Claude.ai から上げられます。企業の管理者は Workspace 全体へ配れます（自動で更新されます）。

公開と API：Skill は GitHub に置けます。導入の手順をREADME.mdにわかりやすく書いてください。アプリを開発しているなら、API のcontainer.skillsから呼ぶこともできます。

どう見せるか：伝えるときは技術ではなく成果に寄せます。「この Skill は数秒で案件の初期設定を終わらせます」と言えるなら、MCP と Skill はそのまま売りになります。

自分の Skill をつくる準備はできましたか

「知識で道具を動かし、自動化をチームの標準にする」

まずは組み込みの skill-creator から始めてみてください。