Claude Skill 作成ワークフロー｜設計から配布まで

Claude CodeのSkillは、保存済みプロンプトやSlash Commandsの言い換えではなく、instructions・scripts・resourcesをひとつのフォルダに束ね、必要な場面でClaudeに読み込ませるための実装単位です。
その入口になるのは SKILL.md と description で、ここが曖昧だと呼ばれ方までぶれます。
実際に私も、descriptionから抽象語を削って対象タスクと入出力を明記した途端、期待した場面でSkillが選ばれる感触が強まりましたし、SKILL.md は短く保って詳細を references/ に逃がした構成のほうが、読み込みの安定感と更新のしやすさが両立しました。
この記事では、最小構成の SKILL.md から、references/ scripts/ assets/ examples/ を使い分ける拡張構成までを、設計→実装→評価→配布の流れで6〜7ステップに分解して再現できる形で整理します。
2026年1月時点の仕様に沿って、配布前にdescription、評価観点、配布先のチェックリストをどう当てるかまで押さえるので、個人用で置くべきか、プロジェクト同梱にするべきか、組織配布に進めるべきかまで判断できるようになります。

Skill とは何かと、ワークフロー全体像

記事の対象は、これからClaudeのSkillを初めて作る人と、1本は動かしたが設計の粗さで詰まり始めた中級手前の人です。
ゴールも絞っていて、最初の1本を「なんとなく動く」状態で終わらせず、設計からテスト、配布の入口まで一続きでたどれる状態を目指します。
その前提として、まず混同を避けたいのが surface の違いです。
Claude.aiClaude CodeAPIでは、Skillの置き場所や呼び出し方、配布の考え方が同じではありません。
本記事はとくにClaude Codeを軸にしつつ、必要な範囲だけ他の面にも触れる整理で進めます。

Skill設計で最初に決めるべきなのは、1つのSkillに何をさせるかです。
ここが曖昧だと、description は広すぎ、SKILL.md は長くなり、テストも評価軸もぼやけます。
逆に、1 Skill 1目的で切ると、入力、出力、トリガーの3点を素直に定義できます。
たとえば「会議メモを要約する」と「会議メモからタスク一覧を抽出する」は近そうでも、期待する出力形式も、失敗時の困り方も違います。
繰り返し発生し、手作業だと抜け漏れや表記ゆれが出やすく、しかも業務固有の観点が必要な仕事ほど、Skillに切り出す価値が出ます。
既存の会話履歴を見返すと、その候補は案外すぐ見つかります。
同じ指示を何度も言い換えている場面、毎回同じ修正を入れている場面、過去の回答に対して「この形式で出してほしい」と後から整えている場面は、要件抽出の材料になります。

Skillと保存済みプロンプト/Slash Commandsの違い

Skillの正式な定義は、instructions と scripts と references や assets をひとつのフォルダに束ねた実装単位で、必要なときにClaudeが参照・起動するものです。
Claude Code Docs:Skillsで整理されている通り、単なる文章テンプレートではなく、構造と再利用を前提にしたパッケージだと捉えると位置づけを誤りません。

保存済みプロンプトとの違いは、再利用の粒度にあります。
保存済みプロンプトは「この文章をまた使う」が中心ですが、Skillは「このタスク一式を、定義済みの入出力と補助資料つきで再利用する」が中心です。
SKILL.md に概要を置き、詳細手順を references/ に逃がし、必要なら scripts/ で決定論的な処理を足せるので、単発の文面では表現しきれない運用まで含められます。
権限管理や配布、評価まで視野に入るのもこの差です。
個人で ~/.claude/skills に置く形だけでなく、プロジェクト同梱や組織配布まで伸ばせるため、最初から「誰が、どこで、何を基準に使うか」を考えた設計が合います。
description は発見・起動の主要な手がかりで、上限は「200 characters」と記載されています。
ただしこの "characters" が単バイト文字（英字）基準なのか、マルチバイト文字（日本語）での扱いかは公式に明示されていないため、日本語での文字数上限を断定する場合は公式 Help Center を参照してください。

私が遠回りしなくなったのも、この切り分けを腹落ちさせてからでした。
会話ベースで作った初版をすぐにテストへ回し、差分を最小限で直すループが最短でしたが、その前提として「これは保存済みプロンプトで足りるのか、Skillとして独立させるべきか」を見誤らないことが効きました。
何でもSkillに入れるのではなく、繰り返し使い、ミスの再発コストが高い仕事だけを切り出すと、設計も運用も軽く保てます。

スキルで Claude を拡張する - Claude Code Docs

Claude Code でスキルを作成、管理、共有して Claude の機能を拡張します。カスタムコマンドとバンドルされたスキルが含まれます。

code.claude.com

フォルダ構造と読み込みの仕組み

Progressive Disclosure は、SKILL.md を概要に留めることを勧める設計方針です。詳細は公式ドキュメントを確認してください。

Progressive Disclosure の設計方針では、Skill の詳細を必要時にだけ読み込む形が推奨されています。
読み込みの厳密なタイミングや挙動は環境や実装に依存するため、実装挙動を断定的に書かず「推奨される設計方針」として扱うのが安全です（公式参照:

description は「何をするSkillか」よりも「どんな場面で呼ぶか」を先に置くと、トリガーとして機能しやすくなります。入力と出力の型まで1文に入ると、曖昧な呼ばれ方が減ります。

6〜7ステップの全体フロー

Skill作成は、思いついた仕様を書き切ってからまとめて検証するより、draft → test → review → revise の反復で詰めるほうがまとまります。
このループが中核です。
本記事では初心者から中級者向けに、これを6〜7ステップへ落として進めます。

1. まず、会話履歴や日々の作業から候補タスクを拾い、1 Skill 1目的で切ります。ここで見るべきなのは、繰り返し頻度、手戻りの多さ、専門知識の有無です。毎回同じ指示を足しているなら instructions 候補、毎回同じ整形ミスが出るなら scripts 候補、判断基準の説明が長いなら references 候補です。

1. 次に、入力、出力、トリガーを定義します。入力は自由記述なのか、ファイルなのか、既存コードなのか。出力は箇条書きなのか、表なのか、JSONなのか。トリガーは「議事録を渡されたとき」なのか、「PRレビュー前」なのか。この3点が曖昧なまま書き始めると、description が弱くなります。

1. その定義をもとに、会話ベースでも手動作成でもよいので初版を作ります。初心者には会話ベースの起点が向いていますが、ここでは完成度より速さを優先します。SKILL.md に目的、成功条件、禁止事項、出力形式だけを入れ、補足資料は後回しで構いません。

1. すぐにテストへ回します。ここで重要なのは、うまくいく入力だけでなく、失敗しやすい入力も混ぜるということです。曖昧な議事録、項目抜けのある原稿、余計なノイズを含むテキストなど、実際に困るケースで見ると、Skillの弱点が早く出ます。

1. テスト結果を review して、どこがズレたのかを切り分けます。説明不足なのか、reference 不足なのか、スクリプト化すべき整形処理なのかを分ける段階です。ここで毎回大改造すると、改善したのか壊したのか追えなくなります。私の経験でも、初版を長く磨くより、テストを先に流して差分だけ直すほうが、設計の癖が見えました。

1. revise では修正範囲を最小に保ちます。description の言い回し、入出力例の追加、reference へのルール移動、script の追加といった単位で直すと、何が効いたかが残ります。とくに description は短い文の差で起動のされ方が変わるので、抽象語を削って用途を前に出す調整が効きます。

1. 仕上げとして、配布先に合わせて置き場所と運用を決めます。個人用ならローカル配置、チームならプロジェクト同梱、横断利用なら組織配布という整理です。API では1リクエストあたり最大 8 Skills という上限もあるため、用途の近いSkillを闇雲に増やすより、呼び分けが明確な単位に揃えたほうが扱いやすくなります。

この流れは、設計→初版作成→実ケース試験→ズレの分析→小さく修正→再試験→配布判断、という短い周回で精度を高めるイメージです。
各工程はそれぞれ設計→draft→test→review→revise に対応します。
Skill 作成で詰まりやすいのは実装の難しさより最初のスコープ設定が広すぎる点で、この周回を小さく回せる設計ほど失敗しにくくなります。

Skill Creator Workflow ｜ anthropics/skills ｜ DeepWiki

This page is a step-by-step reference for the full skill creation lifecycle as implemented by the `skill-creator` skill.

deepwiki.com

1 Skill 1目的と要件抽出のコツ

スコープ設計でまず押さえたいのは、1 Skill 1目的の原則です。
ここでいう「1目的」は、テーマが1つという意味ではありません。
入力を受け取って、ある判断や変換を行い、一定の形式で返すまでの流れが1本につながっている状態を指します。
たとえば「設計レビューを手伝う Skill」は広すぎますが、「TypeScript の PR diff を読み、型安全性と例外処理の観点だけを箇条書きで返す Skill」まで絞ると、何を読ませて何を返すかが定まります。

切り出す候補は、繰り返し発生するタスク、エラーが起きやすいタスク、専門知識が必要なタスクの3つから探すと外しにくい設計です。
毎回ほぼ同じ指示を書いている作業は、Skill 化した瞬間に入力の手間が減ります。
毎回抜け漏れが出る作業は、出力フォーマットを固定すると品質が安定します。
特定ドメインの前提知識が必要な作業は、判断基準を SKILL.md や references/ に寄せることで、会話のたびに説明し直さずに済みます。
実際に使ってみると、この3条件のどれにも当てはまらない作業は、Skill にしても再利用率が伸びません。

要件はゼロから考えるより、既存の会話履歴から抜くほうが速いです。
筆者は会話ログを見返すとき、同じ依頼を3回以上出していたものを先に候補へ入れます。
ここから着手した Skill は、初回でも「もう元が取れた」と感じることが多かったです。
履歴を見るときは、成功した会話だけでなく、出力がぶれた会話も混ぜて読むのがコツです。
うまくいったプロンプトからは入力項目と期待出力を拾えますし、失敗した会話からは禁止事項や不足前提が見つかります。

見るポイントは3つあります。
1つ目は頻出の指示文です。
たとえば「この議事録を要点・決定事項・未解決項目に分けて」「この diff をバグ、設計、テスト観点で見て」のように、言い回しが繰り返されていれば、それが Skill の起動意図になります。
2つ目は入力パターンです。
渡しているものが Markdown の議事録なのか、PR の diff なのか、ログ断片なのかで、Skill の前提が変わります。
3つ目は失敗例で、出力が長すぎた、観点が混ざった、前提を読み違えた、といったズレを拾います。
ここがそのまま設計の制約条件になります。

よくある失敗は、1つの Skill に複数の工程を入れてしまうということです。
たとえば「仕様を整理して、タスク分解して、Issue 化して、優先度も付ける」は一見つながった作業ですが、実際には別々の判断が混ざっています。
こういうときは、出力の単位で分割すると整理できます。
仕様整理の出力は要件一覧、タスク分解の出力は実装タスク、Issue 化の出力はチケット文面、優先度付けの出力は意思決定です。
返すものが4種類あるなら、1本にまとめるより 2〜4 本に分けたほうが安定します。

Claude Codeの Skill はフォルダ単位で指示や補助ファイルを束ねる構造なので、後から scripts/ や references/ を足す前提でも、最初の軸は「この Skill は何を1回で終わらせるのか」に置くのが合っています。
custom Skills の考え方として、description は「いつ使うか」を Claude が判断する材料です。
つまり、スコープが広いほど見つかりにくく、広すぎる説明ほど起動条件がぼやけます。

I/O/トリガーの定義テンプレート

設計段階では、本文を書き始める前に I/O とトリガーを 3〜5 行で下書きしておくと、後の修正範囲が狭くなります。
ここでは Input、Context、Process、Output、Trigger の5つで切ると整理しやすく、SKILL.md に落とし込む前の設計メモとしても扱えます。

テンプレートは次の形で十分です。

1. I（入力）: 何を受け取り、どのような形式で渡されるかを明確にする
2. C（前提）: どの文脈や制約を前提にするかを明記する
3. P（手順）: どの順番で判断・変換するかを定める
4. O（出力）: 何をどんな形式で返すかを定義する
5. T（トリガー）: どんな依頼で呼ばれてほしいか

たとえば「PR レビュー観点抽出」の Skill なら、I は「PR diff と変更意図」、C は「TypeScript プロジェクトで既存コーディング規約に従う」、P は「差分確認→危険箇所抽出→観点分類」、O は「バグ・設計・テストの3見出しで箇条書き」、T は「レビューして」「diff を見て懸念点を出して」のように書けます。
この下書きがあると、description に何を入れるべきかも自然に決まります。

実際にやってみると、入力よりも出力を先に固定したほうがスコープが締まる場面が多いです。
入力は増えがちですが、出力形式を固定すると「その形式に入らない処理は別 Skill」と判断できます。
議事録要約 Skill なら、要点・決定事項・未解決項目の3区分を先に決めておけば、アクションアイテムの担当者抽出まで入れるかどうかを切り分けやすくなります。

トリガー定義では、機能説明ではなく依頼文の形で考えるのが判断材料になります。
「コードレビュー支援 Skill」と書くより、「PR diff を渡されたときに、バグとテスト漏れの観点を返す」のように、呼ばれる場面まで入れたほうが Claude 側の選択条件と合います。
Claude Code Docs: Skillsでも name と description が発見性に関わると整理されており、特に description は「何ができるか」だけでなく「いつ使うか」が要になります。

ここで詰め込みすぎると、SKILL.md が長文化して責務が見えにくくなります。
Claude API 。
設計メモの段階でも同じで、I/O/トリガーは短く固定し、例外ケースや細かな規約は別紙に分けるほうが保守しやすいのが利点です。
巨大な README を読む前から疲れるのと同じで、Skill の入口が長いと、直す側も使う側も判断が鈍ります。

作成方法の比較：会話ベース vs 手動 vs skill-creator

Skill の作成方法は、大きく分けて会話ベース、手動ファイル作成、skill-creator 利用の3つです。
どれが優れているかではなく、どの段階の人に合うかで選ぶと失敗が減ります。

会話ベースは、Anthropicヘルプで案内されている通り、自然言語で目的を伝えながら Skill のたたき台を作る方法です。
向いているのは初心者です。
まだ SKILL.md の粒度感がつかめていない段階でも、会話から初版まで持っていけます。
強みは、とにかく着手が早いということです。
既存の会話ログを貼って「こういう依頼をまとめたい」と渡すと、必要な見出しや description の草案が一気に見えます。
反面、責務の切り方が甘いと、便利そうな機能を1本へ盛り込みやすく、構造制御は弱めです。
最初に作ったものをそのまま完成版にするというより、スコープ確認用のドラフトとして使うと相性が良いです。

手動ファイル作成は、中級者以上に向いています。
SKILL.md、references/、必要なら scripts/ まで自分で組むので、責務境界を厳密に保てます。
入力、出力、禁止事項、補助資料の読み順まで制御できるので、チーム共有前提の Skill ではこの方法が強いです。
特に、どこまでを文章で持ち、どこからを決定論的なスクリプトに渡すかを自分で設計したい場合に向いています。
ただし、最初の設計負荷は高めです。
慣れていない段階だと、広すぎる Skill をきれいなフォルダ構成で作ってしまい、あとから分割する手間が大きくなります。

skill-creator は、その中間に位置します。
draft → test → review → revise の反復ループで作る流れが示されています。
つまり、作るだけで終わらず、テストして直す導線まで含まれています。
初心者から中級者まで使いやすいのは、この反復前提があるからです。
会話ベースより構造化されていて、手動作成ほど最初から全部を理解していなくても進められます。
注意したいのは、仕組みを理解せずに使うとブラックボックス化しやすいということです。
出てきた構成をそのまま受け入れるのではなく、「この Skill の目的は1つか」「description は呼ばれる場面を言えているか」を自分で点検する必要があります。

読者タイプごとの目安を短く整理すると、最初の1本で全体像をつかみたいなら会話ベース、共有運用まで見据えて構造を固めたいなら手動、作成と改善の流れをまとめて回したいなら skill-creator が合います。
筆者は、会話ベースで初版を作り、手動で I/O とトリガーを締め直し、必要なら skill-creator 的な反復で精度を上げる進め方が最も噛み合いました。
特に最初の数本は、どの方法を使うかよりも、広すぎる目的を縮めることのほうが成果に直結します。

この比較で見落としやすいのは、作成方法が違っても、設計で問われる中身は同じだという点です。
1 Skill 1目的に切れているか、既存会話から要件を拾えているか、入力・出力・トリガーが言葉で定義されているか。
この3つが曖昧なままなら、どの作成方法でもあとで修正が広がります。
逆にここが固まっていれば、会話で作っても、手書きで作っても、反復ツールを使っても、Skill の完成度は揃ってきます。

実装フェーズ：SKILL.md とフォルダ構成を作る

最小構成の SKILL.md

実装に入ったら、まずは全Skillで必須の SKILL.md を置きます。
ここが入口です。
Claude Help Center: How to create custom Skillsでは、YAML frontmatter の name と description が発見と起動の判断に関わると整理されており、description は最大 200 characters という制約があります。
設計フェーズで固めた「いつ呼ばれるか」「何を受け取り、何を返すか」を、この短い説明文に圧縮するのが最初の山場です。

体感としても、description を 200字以内で「いつ・何に使うか」と「入出力の型」まで書くようにしてから、過剰にトリガーされる場面が目に見えて減りました。
単に「レビューを支援するSkill」と書くより、「PR diff を入力すると、バグ候補と不足テスト観点を箇条書きで返す」のように、場面と返り値を入れたほうが選択条件が締まります。
ここが曖昧だと、便利そうな一般論として拾われやすくなります。

最小構成なら、ファイルは SKILL.md だけでも成立します。たとえば、次のような形です。

name: pr-review-checker
description: PR diffを受け取り、バグ候補・テスト漏れ・確認観点を箇条書きで返すときに使う。入力はdiff、出力はレビューコメント案。

# Purpose
PR の差分を読み、実装上のリスクと未検証箇所を抽出する。

# When to use

- Pull Request の diff が与えられたとき
- コードレビューの初期観点を短時間で揃えたいとき

# Inputs

- Git diff
- 変更の目的や背景
- 必要なら関連テストの有無

# Outputs

- バグ候補
- テスト漏れの指摘
- レビューコメント案

# Rules

- 断定ではなく根拠付きで指摘する
- 不明点は確認質問として分ける
- スタイル論争より不具合リスクを優先する

この段階では、SKILL.md に全部を書こうとしないのがコツです。
参考: Claude API Docs:Skill authoring best practicesは本文を概要に限定する Progressive Disclosure を推奨しており、SKILL.md 本文を 500 lines 未満に保つのはあくまで推奨事項です。
Skill が少し育ってくると、SKILL.md 単体では苦しくなります。
そこで使うのが Progressive Disclosure です。
考え方は単純で、SKILL.md には概要だけを書き、長文の規約や例、補助ファイルは別ディレクトリへ逃がします。
必要になったときだけ詳細へ進む構造にすると、入口の密度が安定します。

長文化しがちな運用規程を references/ に分けたときは、対話のノイズが減って保守も楽になりました。
1枚の SKILL.md に禁止事項、社内用語集、判定ルール、例外一覧まで積むと、どこを直したかの差分確認だけでも骨が折れます。
詳細を逃がしておくと、入口は短く保てて、深い文書は深い文書として更新できます。

典型的な拡張構成は次の形です。

my-skill/
├── SKILL.md
├── references/
│   ├── policy.md
│   ├── glossary.md
│   └── decision-criteria.md
├── scripts/
│   ├── validate_input.py
│   └── format_output.py
├── assets/
│   └── review-template.txt
└── examples/
    ├── input-sample.md
    └── output-sample.md

それぞれの役割を明確に分けると、構成の保守性が高まり変更が起きても局所的に修正できます。
references/ は長文規程や用語定義、判定基準を置く場所として設計し、SKILL.md は入口としての役割に徹するとよいです。
それぞれの役割をはっきり分けると、構成が崩れません。
references/ は長文の規約、用語定義、判定基準の置き場です。
人が読める文書を増やすなら、まずここに置くのが基本になります。
scripts/ は決定論的に処理したい部分を受け持ちます。
入力形式の検証、JSON整形、定型出力の正規化のように、文章で頑張るよりスクリプトのほうが安定する処理を切り出す場所です。
assets/ は固定ファイル向けで、テンプレートや変わらない付属データを置きます。
examples/ は入出力例の保管庫で、期待する振る舞いを具体化するときに効きます。
SKILL.md 側は、それらの存在を前提にしつつ、入口としての役割に徹します。
たとえば「詳細な判定基準は references/decision-criteria.md（例）を参照」「出力整形は scripts/format_output.py（例）を使う」といった導線を書いておけば、本文を膨らませずに済みます。
読む順番まで決めておくとさらに安定します。
最初に目的と入出力を示し、次に必要な参照先を案内し、最後に例を見る流れにすると、迷子になりません。

拡張構成では、scripts/ をどこまで使うかも分かれ目です。
たとえばレビューコメントの文体統一は文章ルールだけでも運用できますが、出力キーの順番や必須項目の検証はスクリプトに寄せたほうがぶれません。
Skill にやらせる推論と、機械的に確定できる整形処理を分けると、結果の再現性が上がります。

構成方針の比較と選び方

構成は大きく分けて、SKILL.md 一本型、Progressive Disclosure 型、scripts 併用型の3つで考えると整理できます。
違いは「情報量」と「決定論処理の有無」です。

SKILL.md 一本型は、小規模な Skill に向きます。
入出力が単純で、例外ルールも少なく、参照資料を分けるほどではないときに収まりが良いです。
初期の試作や個人用Skillでは、この形が最短距離になります。
ただし、運用ルールや例を足していくうちに、すぐ肥大化します。
入口の文書が育ちすぎると、どこが概要でどこが細則なのかが見えにくくなります。

Progressive Disclosure 型は、中規模から大規模で効きます。
SKILL.md は概要に留め、references/ や examples/ に詳細を逃がすので、トークン消費と保守コストの両方を抑えやすい構成です。
ルールが多いのに、毎回すべてを前面に出す必要はないSkillと相性が良いです。
たとえば社内レビュー規約、文体ガイド、判定基準のような長文を抱えるケースでは、この型のほうが息が長いです。
注意点は、参照導線を SKILL.md に明記しないと、せっかく分離した情報が読まれずに終わるということです。

scripts 併用型は、入力検証や出力整形など、決定論的に処理できる部分がはっきりあるときに選びます。
文章だけで「この形式に揃えて」と頼むより、scripts/validate_input.py や scripts/format_output.py に寄せたほうが、毎回の揺れを抑えられます。
たとえば examples/ の期待出力に合わせて JSON を整形する、必須フィールドの欠落を先に検出する、といった用途です。
その代わり、実行環境を前提にした設計になるので、チーム共有時の前提条件は増えます。

比較をひと目で置くなら、次の整理になります。

まずルール量を見て、その次に機械化できる処理の有無を見ます。
説明だけで完結するなら一本型、規約や定義集が増えるなら Progressive Disclosure 型、形式検証や整形を安定化したいなら scripts 併用型、という順番で考えると迷いません。
API では 1 リクエストあたり最大 8 Skills までという制約もあるので、1本のSkillに情報を詰め込みすぎるより、責務を切ったうえで内部構成を整理したほうが全体運用は軽くなります。

実際には、最初から完璧な構成を選ぶより、SKILL.md 単体で始めて、長くなったルールを references/ に移し、なお決定論処理が欲しくなったら scripts/ を足す流れが自然です。
構成の正解は固定ではなく、Skill の責務が増えたときに、どの情報を入口から外へ逃がすかで決まります。
SKILL.md はあくまで概要に留める、この原則を守るだけで、増築しても崩れにくい土台になります。

評価フェーズ：動作確認・ベンチマーク・改善

スモークテスト

実装がひと通りまとまった段階で、いきなり網羅的な評価に入るより、まず実タスク3件で通るかを見るほうが手戻りを減らせます。
ここで見るのは精密な点数ではなく、「この Skill はそもそも仕事になるか」です。
想定していた入力を渡したときに起動するか、必要な参照先を読むか、出力が最低限の形式を満たすか。
この3点が崩れているなら、後段のベンチマークを積んでも意味が薄くなります。

実際、この段階で不発のパターンは早めに露出します。
description が弱くて呼ばれない、呼ばれても SKILL.md の入口が曖昧で不要な解釈が混ざる、validator に通らない形で出力される、といった問題です。
私は最初にうまくいかなかった事例を2つ残しておくことが多いのですが、これがあると修正の方向性をチームで揃えやすくなります。
成功例だけを見ると「何が効いたのか」の解釈が割れますが、失敗例が並ぶと「ここは直すべき」という合意が早く取れます。

スモークテストでは、draft→test→review→revise のループをできるだけ短く回します。
1回で完成を狙うのではなく、3件の実タスクで可否を見て、失敗した地点をその場で切り分けます。
description が原因なのか、指示本文が原因なのか、スクリプト前提が原因なのかを切り分けられるだけで、修正量は一気に減ります。
とくに scripts 併用型では、モデルの判断ミスと validator の検出結果を混同しないことが効きます。
前者は指示や例の不足、後者は形式や必須項目の定義不足として直すべき場所が異なるからです。

objective/subjectiveでのeval戦略

評価は一律ではなく、objective と subjective を分けたほうが運用が安定します。
客観的に正誤を判定できる Skill には evals を入れるのが基本です。
たとえば JSON 生成、必須フィールドの抽出、所定フォーマットへの変換、判定ラベルの付与のように、期待値を固定できるタスクです。
この種の Skill は、人の目で「だいたい良い」をやるより、自動判定に寄せたほうが改善サイクルが速くなります。

一方で、文体提案、レビューコメントのニュアンス調整、構成の自然さのように主観評価が中心になる Skill では、重い eval を無理に組まないほうが進みます。
軽量なレビューで十分な場面まで自動採点に寄せると、点数は出ても納得感が残らないことが多いからです。
ここでは少人数レビューで観点を揃え、失敗パターンを言語化して SKILL.md や examples に戻すほうが効きます。

この線引きをしておくと、どこに baseline 比較を置くかも明確になります。
objective な Skill では、Skill なしの素の実行や旧バージョンを baseline にして、pass_rate、time、tokens を比較します。
pass_rate が上がったのに time と tokens が跳ねているなら、精度とコストの交換条件を見直すべきです。
逆に tokens が減っても pass_rate が落ちているなら、入口の省略が効きすぎています。
subjective な Skill でも baseline 比較自体は有効ですが、ここでは点数よりレビューコメントの差分を見ます。
「前より安定した」「説明は短くなったが根拠が薄い」といった観点を固定しておくと、改修の方向がぶれません。

運用上は validator→fix→repeat をパイプライン化しておくと、objective 領域の改善が進みます。
skill-creatorの考え方に沿って、まず validator で形式違反や期待値との差を拾い、その結果をもとに fix を当て、再実行して差分を見る流れです。
変更多発の時期ほど、この反復を人力で回すと見落としが増えます。
逆にパイプライン化しておけば、description を少し触っただけのつもりでも起動条件が崩れていないか、出力形式に副作用が出ていないかを回帰テストで追えます。

benchmarkの設計と成果物

ベンチマークは「良くなった気がする」を数字に落とす工程です。
ここで欲しい成果物は、実行結果そのものより、比較可能な記録です。
指標は pass_rate、time、tokens の3つを揃えて、benchmark.json と benchmark.md の両方に残す構成が扱いやすいのが利点です。
機械処理に向くのが JSON、人がレビュー会で読むのに向くのが Markdown という分担です。

『DeepWiki』で整理されているように、集計では mean ± stddev と baseline からの delta を出しておくと、単発の当たり外れに引きずられません。
平均だけだと、たまたま速かった1回に引っ張られますし、標準偏差がないと挙動の暴れ方が見えません。
delta を並べる理由はもっと単純で、「改善した」と言うなら前と比べて何がどれだけ変わったのかを同じ土俵で示す必要があるからです。

たとえば pass_rate が上がって time も下がっていれば、その改修はそのまま採用しやすいのが利点です。
pass_rate は上がったが tokens だけ増えたなら、description の書き換えで起動は良くなった一方、参照の誘導が冗長になった可能性があります。
逆に time は短くなったのに pass_rate が落ちた場合は、短文化によって必要な判断材料まで削っていると考えられます。
この見方ができると、改善の議論が好みではなく構造の話になります。

回帰テストも同じ枠で管理すると、変更のたびに安心して直せます。
とくに description や examples は一見小さい変更でも、トリガー条件や出力の境界を動かしやすい場所です。
そこで benchmark を単発イベントではなく、変更履歴に追随する成果物として残しておくと、「どの変更で崩れたか」を追いやすくなります。
benchmark.md に人が読める短い所見を添えておくと、数値だけでは見えない失敗の質も残せます。

descriptionのトリガー最適化

description は短い説明文に見えて、実際には Skill の入口そのものです。
description は「いつ使うか」を判断する材料として扱われています。
文字数は 200 characters までなので、機能の説明を詰め込むより、どの状況で呼ぶべきかを先に置くほうが働きます。
ここが曖昧だと under-trigger、つまり使うべき場面で起動しない状態が起きます。

description の最適化には、候補データを 60% を training、40% を held-out として分ける方法が有効です。
training 側で文面を調整し、held-out 側でトリガー精度を確認してください。
これにより見たことのある表現への過学習を避け、汎用性を評価できます。

反対に over-trigger も見逃せません。
役割を広く書きすぎると、近いが別物の依頼まで拾ってしまいます。
たとえば「文章を整える」だけでは、レビュー、校正、要約、翻訳の境界が曖昧になります。
ここで効くのは、対象タスクの名詞より、起動条件の文脈を書くということです。
どんな入力を受けたときに、何を返す Skill なのかを一文で固定すると、誤起動が減ります。
description は短い看板というより、ルーターの条件式に近いと捉えたほうが調整の勘所が見えます。

この調整でも、最初に失敗例を残しておくやり方が役立ちます。
呼ばれなかった依頼文と、呼ばれてはいけないのに拾った依頼文をそれぞれ2つほど固定しておくと、under-trigger と over-trigger の両側から改修できます。
description の改善は文才の話に見えますが、実際には誤判定の切り分け作業です。
どの言い回しが起動条件として効いて、どの言い回しがノイズになるかを held-out test で確かめながら詰めると、運用に入ってからの事故が減ります。

How to create custom Skills ｜ Claude Help Center

support.claude.com

配布フェーズ：個人・プロジェクト・組織への展開

個人：~/.claude/skills とzipアップロード

反対に over-trigger（誤起動）も欠かせません。
役割を広く書きすぎると、近いが別物の依頼まで拾うため、対象タスクの文脈や期待する出力形式を明確に一文で示すと効果的です。

zip アップロードは、ローカルのフォルダ構成をそのまま束ねて持ち込みたいときに便利です。
とくに SKILL.md だけでなく references/ や scripts を同梱している Skill では、単一ファイルの受け渡しより事故が少なく、試用の立ち上がりも速くなります。

個人配置の弱点は、使える人が自分に閉じるということです。
同じ Skill をチームで回したくなった瞬間に、誰のホームディレクトリに何版が入っているのかを追い始めることになります。
個人用としては軽快でも、共有資産として見ると履歴と責任の所在が曖昧になりやすいので、試作から運用へ移るタイミングでは置き場所を切り替える前提で考えるほうが収まりがいいです。

プロジェクト：.claude/skills/ 同梱と運用ポイント

プロジェクト単位で安定運用したいなら、リポジトリ配下の .claude/skills/ に同梱する形が本命です。
コード、テスト、Skill の定義を同じ変更セットで管理できるため、「このブランチではどの Skill が前提か」が履歴に残ります。
小規模チームではこの形がいちばんハマり、環境差分が目に見えて減りました。
誰かの ~/.claude/skills にだけ修正版が入っていて、ほかのメンバーは古い挙動のまま、というズレが起きにくくなります。

この置き方が効くのは、Skill をプロジェクトの一部として扱えるからです。
たとえば API スキーマの整形 Skill やレビュー補助 Skill のように、そのリポジトリ固有の文脈が必要なものは、個人領域に置くより .claude/skills/ のほうが筋が通ります。
実装フェーズで作った SKILL.md、参照資料、補助スクリプトがコードベースと一緒にレビューされるので、変更理由も追えます。

運用では、Skill 名と役割の境界をリポジトリ内で重複させないことが効きます。
似た説明の Skill を複数同梱すると、呼ばれるべき場面が分散し、評価フェーズで詰めたトリガー条件も濁ります。
加えて、プロジェクト同梱は再現性を上げる一方で、配布範囲はそのリポジトリに参加しているメンバーへ限られます。
横断的に使いたい Skill を増やしていくと、同じものを複数リポジトリに持つ運用になりやすく、そこで組織配布の必要性が見えてきます。

面ごとの優先順位もここで押さえておきたいところです。
競合時の扱いは enterprise > personal > project の順で考えると整理しやすく、組織で配られた Skill が最優先、その次に個人領域、プロジェクト同梱が続くという理解で運用設計をすると衝突を把握しやすくなります。
名前や説明が近い Skill を別面に置く場合は、この優先順位を前提に命名をずらしたほうが混乱が減ります。

組織：organization-wide management とガバナンス

マーケットプレイス/プラグイン最新動向

2025年末以降の流れで目立つのは、Skill の配布がローカル配置だけで閉じず、plugin/marketplace の文脈へ広がってきたということです。
The Complete Guide to Building Skills for Claudeでも、個人は zip アップロードまたは skills directory 配置、組織は admin 配布という二層構造が案内されており、その外側に open standard と partner-built skills の流れが重なっています。
つまり、手元で作った Skill を自分だけで使う段階、チームで共有する段階、組織や外部パートナー経由で流通する段階が分かれ始めています。

plugin/marketplace の文脈で気をつけたいのは、配布チャネルが広がるほど「どこに置くと誰が使えるか」が技術の話だけでは済まなくなるということです。
個人配置は最速、プロジェクト同梱は再現性、organization-wide management は統制という役割分担があり、マーケットプレイス的な流通はそのさらに外側で discoverability を担います。
便利そうに見えても、組織の標準に載せるかどうかは別判断になります。

配布先ごとの違いを並べると、次のように整理できます。

この並びで見ると、置き場所は単なる保存先ではなく、利用範囲と責任範囲を決めるレイヤーです。
個人で磨いた Skill をそのまま組織へ持ち込むのではなく、どの面で誰に使わせるのかを先に決めると、配布後の混乱が減ります。
優先順位が enterprise > personal > project であることも、その整理に沿っています。
どの Skill が最終的に前面に立つのかを先に理解しておくと、同名衝突や役割重複を配布前に潰せます。

よくある失敗と回避策

スコープ/description/本文量のアンチパターン

初心者が最初に踏みやすいのは、1つの Skill に何でも入れてしまうということです。
たとえば「記事作成支援」という名前で、構成出し、本文執筆、SEO調整、校正、要約まで抱え込むと、呼ばれる条件も出力の型も散っていきます。
こうなると Claude 側から見ても「いつ起動すべきか」が判定しづらくなり、人が読んでも責務がつかめません。
実運用では、1 Skill 1目的まで切り分けたほうが安定します。
構成専用、校正専用、メタディスクリプション専用のように分けるだけで、失敗時にどこを直すべきかも追いやすくなります。

description の曖昧さも、呼び分けの失敗を招く定番です。
「文章作成を助ける」「必要に応じて品質を上げる」といった説明は、人間には雰囲気で伝わっても、起動条件としては弱いままです。
Claude Help Center: How to create custom Skillsでも description は発見と起動の判断材料とされ、長さも 200 characters までに収める前提になっています。
ここで効いたのが、一文目を「このSkillはXのために使う」で始める書き方でした。
私はこの形にしてから、誰向けで、どの場面で、何を返す Skill なのかが人にも AI にも伝わりやすくなりました。
200字以内に詰めるなら、入出力、対象タスク、境界条件の3点を書くとぶれません。
たとえば「このSkillは技術記事の見出し構成案を作るために使う。
入力はテーマと読者像、出力はH2/H3案。
本文執筆やSEO監修は扱わない」と書けば、用途の輪郭が一気に締まります。

本文の詰め込みすぎも別の落とし穴です。
SKILL.md に背景説明、運用ルール、例外処理、参考資料、FAQまで全部入れると、途中から「使い方」ではなく「資料置き場」になります。
SKILL.md 本文を 500 lines 未満に収めるのも、この肥大化を避けるためだと捉えると腑に落ちます。
実際、500行に近づくころには、追記するたびに全体の見通しが悪くなり、編集のたびに別の箇所を壊しやすくなります。
本文は運用ガイドに徹し、長い具体例や補足資料は references/ に退避したほうが保守の摩擦が減ります。
巨大な README が新しい参加者を遠ざけるのと同じで、巨大な SKILL.md は Skill の改善速度そのものを落とします。
SKILL.md を長くしすぎると編集やレビューの摩擦が増すため、長い具体例や補足は references/ に移す方が保守性が高まります。
大きな README が新参加者の障壁になるのと同様です。

Skill authoring best practices

Learn how to write effective Skills that Claude can discover and use successfully.

platform.claude.com

evalsのやりすぎ問題と線引き

評価が必要だと聞くと、どの Skill にも細かい evals を付けたくなります。
ただ、ここで空回りしやすいのが、主観タスクまで機械判定で押し切ろうとするケースです。
コピーの語感、文章の読み味、トーンの自然さ、ブランドらしさのような仕事は、正解が一つに定まりません。
にもかかわらず pass/fail を細かく定義しようとすると、テストを通る無難な出力ばかりが残り、現場でほしい表現が削られます。

このタイプのタスクでは、evals を増やすより、人間レビューの基準を先に整えたほうが前に進みます。
私がうまくいったのは、採点ロジックを複雑にする代わりに、レビュー基準シートと良い例・悪い例をそろえるやり方でした。
たとえば「読者像に語り口が合っているか」「禁止表現を踏んでいないか」「情報の順序が読み手の負荷を増やしていないか」のように、見る観点を固定します。
これなら評価者が増えても会話が噛み合いやすく、Skill 側の修正点も見えます。
客観評価が効くのは、整形、抽出、変換、検証のように正誤を比較できる領域です。
主観タスクでは、人間レビューに寄せる線引きのほうが結果的に安定します。

もちろん、人手中心にすると何も測れなくなるわけではありません。
最低限のガードレールとして、禁止事項の逸脱、出力形式の崩れ、必須要素の欠落だけは自動チェックに寄せられます。
そこで機械に任せる部分と、人間が読む部分を分けると、テストは引き締まりつつ、表現の幅は残せます。
評価設計で詰まり続ける Skill は、Skill の品質より先に「この仕事は何をもって成功とするか」が曖昧なことが多いので、まずそこを言語化したほうが早く進みます。

Skill数と呼び分け精度のバランス

Skill は増やせば増やすほど便利になる、とは限りません。
似た役割の Skill を並べすぎると、今度はどれを呼ぶべきかの境界が濁ります。
しかも API では同時に扱える Skills に上限があり、1リクエストで最大 8 Skills までです。
ここを無視して「全部入り」で設計すると、管理上はそろっていても、実際の呼び分けでは recall が落ちます。
本来拾いたい依頼が、名前や description の似た別 Skill に埋もれてしまうからです。

典型例は、校正系の Skill を細かく増やしすぎるパターンです。
「誤字脱字修正」「表記統一」「語調調整」「冗長表現削減」「読みやすさ改善」がそれぞれ独立していて、description も似た言い回しだと、使い分けの精度は上がるどころか下がります。
分割が悪いのではなく、分割した単位に対して呼び分けの言葉が足りていません。
こういうときは Skill の数を増やす前に、利用シーンごとにセットを分けるほうが効きます。
編集セット、分析セット、変換セットのように束ね、同時に載せる候補を絞ると、各 Skill の役割が立ちます。

数を増やす設計では、precision だけ見ていると判断を誤ります。
誤起動が減っても、本命が呼ばれないなら運用では困ります。
私の感覚では、Skill を追加したあとに「これで守備範囲が広がった」はずなのに、実際には以前より呼ばれないタスクが増えたとき、増やしすぎのサインが出ています。
特に組織配布では、部門ごとのローカル最適で Skill が積み上がりやすく、全体では似たものが増殖しがちです。
そうなる前に、目的別に再編し、description の一文目で役割を明確に切り分けておくと、呼び分けの精度が戻ります。

Skill 設計は、細かく分ければ勝ちでも、数を絞れば勝ちでもありません。
役割が一目でわかる単位まで分解しつつ、同時に候補へ並ぶ数は絞る。
そのバランスが崩れると、Skill を増やしたのに前より扱いにくい状態に入ります。
こうした失敗は実装より前、名前、description、束ね方の3点でほぼ決まります。

最初の1本を作る実践テンプレート

読んだ直後に手を動かすなら、まずはひとつだけ繰り返し出てくる作業を選び、その作業にだけ効く最小の Skill を置くのが近道です。
私は最初、構成を考え込みすぎて止まりましたが、テンプレをそのままコピペして必要最小限だけを追記する運用に変えてから、初回作成の迷いが減りました。
最初の1本は完成度より、目的と出力の輪郭がぶれないことを優先したほうが、その後の改善が進みます。

最小 SKILL.md テンプレート

手動で作る場合は、Skill 用のフォルダを作り、その中に SKILL.md を置くところから始めます。
構造や配置の基本はClaude Code Docs: SkillsとClaude Help Center: How to create custom Skillsの案内に沿えば十分で、最初から references/ や scripts/ を増やす必要はありません。
会話ベースで着手したいならAnthropicヘルプ:会話で Skill を作る方法から入れますし、作成から評価まで一気に進めたいならanthropics/skills: skill-creator（https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.mdを参照すると流れをつかめます）。

最小構成は次の形で足ります。description は「いつ呼ぶ Skill か」が一読で伝わる文にしておくと、あとで直す箇所が減ります。

name: meeting-note-cleanup
description: Clean rough meeting notes into a concise summary with decisions, action items, owners, and open questions. Use when notes are messy but facts must stay unchanged.

{{ogp:https://support.claude.com/ja/articles/12599426-claude-%E3%81%A8%E3%81%AE%E4%BC%9A%E8%A9%B1%E3%82%92%E9%80%9A%E3%81%98%E3%81%A6%E3%82%B9%E3%82%AD%E3%83%AB%E3%82%92%E4%BD%9C%E6%88%90%E3%81%99%E3%82%8B%E6%96%B9%E6%B3%95|Claude との会話を通じてスキルを作成する方法 ｜ Anthropicヘルプセンター||https://downloads.intercomcdn.com/i/o/lupk8zyo/792494/717b10d3ebd874823db64841659b/76f3062d78ebbb04863fb1de3ef9cca0.png}}

# Purpose
雑多な会議メモを、事実を変えずに要約・整理する。

# When to use

- 箇条書きのメモから要点だけ抜き出したいとき
- 決定事項、担当者、未決事項を分けて整理したいとき

# Inputs

- 会議メモ本文
- 必要なら参加者名や会議名

# Instructions
1. 事実を補わず、記載内容だけで整理する。
2. 決定事項、アクション、担当者、未決事項を分ける。
3. 曖昧な表現は「不明」とせず、原文のまま保持する。
4. 出力は指定フォーマットに合わせる。

# Output format
## Summary
2〜4文の要約

## Decisions

- ...

## Action Items

- [担当者] 作業内容

## Open Questions

- ...

# Example
入力例:

- 新LPを来週公開予定。画像差し替え担当が決まっておらず、CTA文言は未確定。
- 画像差し替えは田中さんが担当予定だが、まだタスクが未確定。
出力例:
## Summary

- 新LPは来週公開予定です。画像差し替えは田中さんが担当予定で、CTA文言は未確定です。

## Decisions

- 新LPの公開日は来週に設定

## Action Items

- [田中さん候補] 画像差し替え担当の確定（期限: 次回ミーティングまで）
- 画像差し替え担当を確定する（田中さん候補）
- CTA文言の確定（担当者未設定）
## Decisions

- 新LPは来週公開

## Action Items

## Open Questions

- CTA文言の確定

この段階では、長い背景説明よりも「何を入れると、どう返すか」が読めることを優先します。
本文が膨らみ始めたら、前述の通り詳細例や補足だけを references/ に逃がす形にすると、SKILL.md 自体の見通しを保てます。

設計チェックリスト

最初の1本は、書く前に設計を短く固めると失敗が減ります。以下の7点が埋まっていれば、試作としては十分です。

• 目的: その Skill が片づける仕事は1つに絞れているかを確認する
• 入出力: 何を受け取り、何を返すかが具体的に書けているかを確認する
• トリガー: どんな依頼文や状況で呼ばれたいかが想像できるかを確認する
• 前提: 事実を補わない、外部調査をしない、既存フォーマットに従うなどの条件があるかを明示する
• 例の有無: 良い入力例と期待出力の対が最低1つあるかを確認する
• 境界条件: 情報不足、曖昧な入力、長文、禁止事項の扱いが決まっているかを決めておく
• 期待出力フォーマット: 見出し、箇条書き、JSON風、表など返答の形が固定されているか

このチェックリストで詰まりやすいのは、目的ではなくトリガーです。
「文章を整える」のような広い言い方だと、似た Skill と境界が重なります。
そこで、依頼文を頭の中で具体化して、例えば「会議メモを決定事項付きで整理したい」「レビューコメントを修正タスクに変換したい」のように、作業シーンまで落とすと description も本文も書きやすくなります。

次のアクション

実際に配る前は、公開物というより運用物として点検したほうが抜け漏れを減らせます。配布前チェックとして見ておきたいのは次の項目です。

• 配置先のパス表記が正しいか。個人配置なら ~/.claude/skills、プロジェクト同梱なら .claude/skills/ と書き分ける
• description が 200 characters 以内に収まり、その文面で呼ばれる根拠を自分で説明できるかを確認する
• SKILL.md 本文が 500 lines 未満に収まっているかを確認する
• ベンチマークやテストの記録を残しているか。最低でも試した実タスク、通った点、崩れた点は残す
• 配布面と優先順位を決めたか。まずは enterprise より personal、personal より project ではなく、運用上は enterprise > personal > project の候補を意識しつつ、実際に最初に試す場所は最小範囲から選ぶ
• 確認日を明記したか。配布方法の記述は 2026年1月時点の案内に合わせる

このあとやることは単純です。
繰り返し作業を1つ選び、最小構成の SKILL.md を作り、実タスク3件で試します。
その3件で同じ補足説明を何度も足しているなら、そこだけを references/ や scripts/ に分けます。
そこまで見えた段階で、個人配置に置くのか、プロジェクト配下に入れるのか、組織へ広げるのかを決めれば、最初の1本がそのまま運用の土台になります。