skill-creation-walkthrough

独自の Claude Skills の設計、作成、保守について順を追って説明します。どのような場合にスキルが適しているのか、実際にスキルを起動する説明の書き方、SKILL.md と参照ファイルの構成方法、テストと改善の方法を取り上げます。

使用する場面

• 同じプロンプトや指示を何度も書いていることに気づいたとき。
• ワークフローやフレームワークを再利用できる形にまとめたいとき。
• 作成したスキルが、起動されるべき場面で起動されないとき。
• 他の人が使うスキルを公開するとき。
• Claude に特定の分野に応じた作業方法を教えたいとき。
• 他の人が作成したスキルをレビューし、品質基準が必要なとき。

使用しない場面

• 一度きりのプロンプトの場合（そのままプロンプトを書いてください）。
• プログレッシブディスクロージャーではなく、システムコンテキストに置くべき情報の場合。
• すべての会話における Claude の一般的な振る舞いを変更したい場合（スキルではなく、Claude.ai の設定またはシステムプロンプトを使用してください）。
• ツール呼び出しを置き換える場合（スキルは指示であり、ツールではありません）。

必要な入力

• 形式化したいタスクまたはワークフロー。
• 対象ユーザー：誰が、どのような会話でこのスキルを起動するのか。
• 既存の成果物：これまでに使ったプロンプト、作成したドキュメント、良い出力の例。

フレームワーク：スキルの仕組み

スキルは、SKILL.md ファイルを含むフォルダーです。SKILL.md には、YAML フロントマター（名前と説明）と指示を記した本文があります。必要に応じて読み込まれる参照ファイル、スクリプト、テンプレートを含めることもできます。

重要な特性は、プログレッシブディスクロージャーです。Claude は毎回、すべてのスキルを読み込むわけではありません。スキルの説明はシステムプロンプトに置かれます。SKILL.md の本文と参照ファイルは、スキルが起動されたときにのみ読み込まれます。そのため、コンテキストを圧迫せずに、何百ものスキルをユーザーが持つことができます。

これが意味すること：

• 起動の成否は説明にかかっています。適切に書かなければ、スキルは読み込まれません。
• SKILL.md の本文には、ワークフローを記述します。
• 参照ファイルには、長いチェックリスト、テンプレート、例、詳細な参考資料など、毎回の呼び出しで必要とされない内容を置きます。

ワークフロー

フェーズ 1：スキルが適切か判断する

すべてをスキルにする必要はありません。次の基準で判断してください。

スキルにすべき兆候	スキルにすべきでない兆候
同じワークフローを 5 回以上繰り返しています。	使ったのは一度だけです。
出力の形式を統一すると効果があります。	出力は毎回、個別に作り込む必要があります。
タスクを起動する明確な条件（質問の形式、ファイルの種類、分野）があります。	そのタスクはすでにすべての会話に含まれています。
指示が 200 語を超えています。	1 行のシステム指示で十分です。
テンプレートや参考資料が役に立ちます。	通常の文章だけで十分です。
同じワークフローが他の人にも役立つ可能性があります。	自分の単一プロジェクトでしか役立ちません。

左の列に当てはまる回答が多ければ、スキルを作成してください。そうでなければ、保存したプロンプトまたはシステム指示を使ってください。

フェーズ 2：起動条件を定義する

何かを書く前に、次の点を確認してください。このスキルはいつ読み込まれるべきでしょうか？

具体的に定めてください。起動するきっかけとなる正確な表現や状況を書き出します。例：

• 「ユーザーがクリエイティブブリーフ、キックオフドキュメント、またはプロジェクト概要の作成を依頼したとき。」
• 「ユーザーが CSV をアップロードし、表形式の分析を希望したとき。」
• 「ユーザーが『X で上位表示するには？』『スキーマを追加すべき？』と尋ねたときや、SEO に関することを尋ねたとき。」
• 「ユーザーがベンダーを選びたい、またはツールを比較したいと言ったとき。」

起動条件を記述するのが、説明の役割です。起動条件を明確に表現できなければ、スキルは安定して読み込まれません。

フェーズ 3：説明を記述する

これは、スキルの中で最も重要な一文（または二文）です。説明はシステムプロンプト内で Claude が確認し、そのスキルを読み込むかどうかを判断するために使われます。

優れた説明には、次の 4 つの要素があります。

1. 何をするか（行動を示す一文）。
2. いつ使うか（トリガーとなるフレーズや状況）。
3. エッジケース：「次の場合にもトリガーされます…」として、気づきにくい状況を拾います。
4. 役立つ対象…（対象ユーザーやユースケース。適切なスキルを選びやすくなります）。

良くない説明：

「SEO を支援します。」

なぜ良くないのか：曖昧で、トリガーとなるフレーズがなく、ユーザーが実際に必要としているときに起動しません。

良い説明：

「単一の URL または少数のページのオンページ SEO を監査します。ユーザーがページ監査を依頼したとき、タイトルやメタディスクリプションを最適化したいとき、「なぜこのページはランキングされないのか」と質問したとき、または URL を共有して問題点を尋ねたときに使います。ユーザーが Core Web Vitals、内部リンク、またはスキーママークアップに言及した場合にもトリガーされます。個別ページのレビューにも、小規模な一括監査にも役立ちます。」

なぜ良いのか：具体的なアクション、複数のトリガーフレーズ、エッジケース、対象ユーザーが明確です。

フェーズ 4：SKILL.md の本文を構成する

一貫した構成にすると、スキルが読みやすく、保守しやすく、AI にとっても扱いやすくなります。以下のパターンは、ほとんどのスキルで使えます。

---
name: [your-skill-name]
description: [your description]
---

[One-sentence purpose statement]

## When to use
[Bulleted list of trigger situations]

## When NOT to use
[Bulleted list, ideally redirecting to sibling skills]

## Required inputs
[What Claude needs from the user to run this skill]

## The framework
[The durable IP: the model, the steps, the dimensions, the layers]

## Workflow
[Numbered steps Claude follows]

## Failure patterns
[Common mistakes to avoid or push back on]

## Output format
[What the deliverable looks like]

## Reference files
[List of files in the references/ folder with descriptions]

すべてのスキルにすべてのセクションが必要なわけではありません。手順だけを扱うスキルでは、「framework」を省略するものもあります。例を多く含むスキルでは、「Examples」セクションを追加することもあります。この構成を出発点として、必要に応じて調整してください。

フェーズ 5：SKILL.md に含めない情報の参照資料を追加する

参照資料は、段階的な開示の第 2 層です。デフォルトではなく、Claude が参照資料を読み込んだときに読み込まれます。

参照資料には、次のようなものを含めます。

• 長いチェックリスト（100 項目の監査チェックリストなど）。
• 実例付きのテンプレート。
• 特定のシナリオ向けの詳細なプレイブック。
• 仕様へのリンク、用語集、判断テーブルなどの参考資料。
• すべての呼び出しで必要とは限らない、100 行を超える情報。

各参照資料は単独で使えるようにしてください。スキルが提供するコンテキストがあれば、読者（または Claude）が SKILL.md を先に読まなくても使える状態にします。

効果的な命名パターン：

• テンプレートには references/[noun]-template.md。
• チェックリストには references/[noun]-checklist.md。
• エンドツーエンドの手順書には references/[noun]-playbook.md。
• 実例には references/example-[scenario].md。

SKILL.md の「Reference files」セクションから参照ファイルを参照し、それぞれに一行の説明を添えてください。

フェーズ 6：テストして改善する

スキルは最初からうまく動くとは限りません。改善を繰り返すことを想定してください。

テスト用チェックリスト：

• トリガーテスト：新しい会話でトリガーフレーズを入力します。スキルは読み込まれますか？読み込まれない場合は、説明が狭すぎるか、適切ではありません。
• エッジケーステスト：「次の場合にもトリガーされます…」の節によって起動するはずの内容を入力します。起動しますか？
• 誤検知テスト：関連性は近いものの、実際には対象外の内容を入力します。スキルは読み込みを回避しますか？常に読み込まれる場合は、説明が広すぎます。
• 出力テスト：実際のタスクでスキルを実行します。期待した出力になりますか？
• 長さテスト：SKILL.md は 250 行未満ですか？参照資料は 400 行未満ですか？超えている場合は、分割するか短くしてください。

テスト後によくある修正：

• スキルが起動しない → 説明を広げ、明示的なフレーズを追加し、「次の場合にもトリガーされます…」を加える。
• スキルが頻繁に起動しすぎる → 説明を絞り、「次の場合はトリガーしないでください…」を追加し、対象ユーザーをより具体的にする。
• 出力が一般的すぎる → より明確なフレームワークや、具体性を増したワークフローを追加する。
• 参照資料が分かりにくい → 複数の参照資料に分割し、それぞれの焦点を絞る。

詳細：説明の構成

説明をうまく書くのは難しいものです。ここでは、その形式を詳しく説明します。

文 1：何をするか

動詞から始め、具体的にします。

• 良い例：「オンページ SEO を監査する。」
• 悪い例：「SEO 関連のことを支援する。」

文 2: いつ使うか

主なトリガーを明記します。ユーザーが実際に口にするであろうフレーズを使用してください。

• 良い例: 「ユーザーがページ監査を依頼したとき、タイトルとメタディスクリプションを最適化したいとき、または『なぜこのページはランキングされないのか』と尋ねたときに使用します。」
• 悪い例: 「SEO の改善に使用します。」

文 3: 「次の場合にもトリガーされます...」

二次的なトリガーとエッジケースを捕捉します。

• 良い例: 「ユーザーが Core Web Vitals、内部リンク、またはスキーママークアップに言及したときにもトリガーされます。」
• 悪い例: (省略)

文 4: 次の場合に役立ちます...

対象読者や範囲を説明して、曖昧さの解消に役立てます。

• 良い例: 「個々のページレビューと小規模バッチ監査の両方に役立ちます。」
• 悪い例: (省略)

スキルの説明が 1 文であるなら、おそらく十分に具体的ではありません。

深掘り: 実例

技術的なポストモーテム文書をいつも書いていて、それをスキル化したいと想像してください。

ステップ 1: スキルだと判断する。 年に 5 回以上ポストモーテムを書き、一貫性によって成果が向上し、チームの他のメンバーも使うでしょう。はい、スキルを構築します。

ステップ 2: トリガー。 「ユーザーがポストモーテム、振り返り、または事後報告書を書きたいとき。インシデントが発生し、何がうまくいかなかったかをレビューしているとき。」

ステップ 3: 説明。

「インシデント、障害、または重大なプロジェクトの失敗の後に、構造化されたポストモーテムを書きます。ユーザーがポストモーテム、振り返り、事後報告書、RCA に言及したとき、またはインシデント後に『なぜこれがうまくいかなかったのか』と尋ねたときに使用します。ユーザーがローンチ、プロジェクトの失敗、またはインシデントのデブリーフから学んだ教訓を記録したいときにもトリガーされます。技術的なインシデント、プロジェクトの振り返り、チームの学習レビューに役立ちます。」

ステップ 4: SKILL.md の本文。 標準的な構造を使用します。必要な入力 (タイムライン、影響、貢献者)。フレームワーク (なぜなぜ分析、寄与要因、アクションアイテム)。ワークフロー (事実の収集、草案、レビュー、配布)。失敗パターン (責任追及、曖昧なアクションアイテム、フォローアップなし)。

ステップ 5: 参照。 文書構造を含む post-mortem-template.md と、ポストモーテム会議を進行するための facilitator-checklist.md。

ステップ 6: テスト。 「昨日障害がありました。ポストモーテムを書くのを手伝ってもらえますか?」でトリガーします。発火するはずです。「ポストモーテムとは何ですか?」でトリガーします。これもおそらく発火するはずです。「四半期を振り返りましょう」でトリガーします。発火しないはずです (これは別の種類の振り返りです)。

トリガーが正しく発火するまで反復し、その後リリースします。

失敗パターン

• 説明が狭すぎる。 説明がユーザーが言わない正確なフレーズを要求するため、スキルがまったく発火しません。
• 説明が広すぎる。 無関係なタスクを含め、スキルが常に発火します。
• トリガーフレーズがない。 説明はスキルが何をするかを述べていますが、いつロードするかを述べていません。トリガーが信頼できません。
• SKILL.md が長すぎる。 1,000 行の SKILL.md は段階的開示の目的を損ないます。参照に分割してください。
• SKILL.md を複製する参照。 参照が本文の内容を繰り返している場合は、どちらかを削除してください。
• 「使用しない場合」がない。 兄弟スキルと重複するスキルは曖昧にロードされます。兄弟スキルを明示的に相互参照してください。
• 例がない。 実例のないフレームワークは適用が困難です。参照資料に少なくとも 1 つ含めてください。
• 1 つの例に最適化する。 単一のユースケースに合わせて書かれたスキルは、隣接するケースで失敗します。一般化してください。
• 反復がない。 スキルを一度リリースして、二度と見直さない。スキルは劣化します。年に一度監査してください。
• 公開スキルにおけるブランディングや製品固有の前提。 汎用的であるべきスキルは、あなたのスタックをハードコードすべきではありません。公開スキルは方法論 (フレームワーク、意思決定基準、分類法、アンチパターン) を教えます。実装の詳細 (特定のページアーキテクチャ、型定義、コンポーネントコード、フレームワーク固有のパターン) は内部プレイブックに属します。完全な規律とそれが重要であるユーザー成果の理由については、references/methodology-vs-implementation.md を参照してください。

出力形式

このスキルを使って別のスキルを作成する場合は、次の内容を提出してください。

1. トリガー分析：スキルを起動すべきフレーズや状況の簡潔なリスト。
2. 説明文の草案：YAML フロントマター用の 2～4 文の説明文。
3. SKILL.md 本文：標準的な構成に従った、スキルの全文。
4. 参照ファイルの計画：作成する参照ファイルと、それぞれの簡潔な説明のリスト。
5. 最初の参照ファイル：出発点として、少なくとも 1 つの参照ファイルを最初から最後まで作成。
6. テスト計画：スキルを起動すべきテストプロンプト 3～5 件と、起動すべきでないテストプロンプト 2～3 件。

参照ファイル

• references/skill-template.md：注釈付きのセクションガイドを含む、空の SKILL.md テンプレートです。コピーして記入できます。
• references/description-cookbook.md：監査、テンプレート、フレームワーク、ウォークスルーなど、よくあるスキルの種類に対応した説明文のパターンと具体例をまとめています。
• references/methodology-vs-implementation.md：公開するスキルに含める内容と内部にとどめる内容、そしてこの方針がユーザーにもたらす利点を説明しています。監査パターンと、スキルを方法論に特化させるための作成チェックリストも含まれています。