generate-skill

スキルを生成する

概要

agentskills.io のスキル作成ページ、Anthropic の skill-creator、プラットフォームのプロンプトガイド、および実証的なアクティベーション研究の規約に沿って、すぐに公開できる SKILL.md を1つ生成します（必要に応じて references/、scripts/、assets/ も作成します）。Phase 4 の調整リストは Claude 5 世代向けに最適化されています。世代が変わったら、現在のモデルのプロンプトガイドと照らし合わせて再確認してください。

1つのスキルにつき、1つの役割。 このスキルの役割は、SKILL.md とそのフロントマターの作成です。ドキュメント、リリース、補助ファイルは対象外です。

以下の2つの原則が、すべてのフェーズの指針となります。

• 説明がプロダクトです。 スキルを呼び出すかどうかを Claude が判断する際に読むのは、これだけです。プロンプトのように調整してください。
• エージェントにない知識を追加し、すでに知っていることは省きます。 指示ごとに、「これがなければエージェントは間違えるか」と問いかけてください。そうでなければ削除します。推論できない、手順に関する、スキル固有の知識だけを記述してください。

ナビゲーション

読み込むもの	タイミング
references/PATTERNS.md	Phase 4 — 選択したタイプの本文テンプレート
references/FRONTMATTER.md	Phase 3 — オプションのフィールド、アンチパターン、3段階の移植性
references/EXAMPLES.md	説明文と本文の手順の✅／❌ペア
references/SOURCES.md	ユーザーがルールに異議を唱え、仕様の根拠を示す必要がある場合

ワークフロー

AskUserQuestion を使い、質問は一度に1つずつ行ってください。質問票をまとめて一気に提示してはいけません。各フェーズの後に成果物を示し、次へ進む前に確認してください。

Phase 1 — 要件の把握

1. 目的。 このスキルが担う役割を1文で説明します。
2. タイプ。 本文テンプレートを決定します。methodology（複数ステップのワークフロー — code-review、track-session）・technical（API、フォーマット、ツール — docx、semantic-release）・auditing（成果物を評価 — rate-skill、security-review）・reference（スキーマ、規約、参照表 — bigquery）・automation（スクリプトまたは外部コマンド — screenshot-local）。
3. トリガーフレーズ。 実際のユーザーが使いそうなフレーズを、5つ以上、原文のまま挙げます。自然な表現を促してください。「create a skill」のように、「scaffold skill artifact」のような言い回しは避けます。
4. 対象外の範囲。 どの近接分野のスキルの役割を奪わないようにしますか？ これは Do NOT use… 句と、Phase 8 の評価セットの「起動すべきでない」側を決定します。
5. 強制レベル。 提案、ガイド付き（チェックリスト）、または厳格（ゲート付きフェーズ）から選びます。デフォルトは、methodology と auditing がガイド付き、technical／reference／automation が提案です。

Phase 2 — 説明文の作成

公式の長さの目安は「数文から短い段落まで」で、上限は1024文字です。構成は次のとおりです。

<Third-person noun phrase>. Use whenever the user <wants/asks to> <trigger 1>, "<trigger 2>", or <trigger 3> — even if they don't explicitly mention <domain term>. Do NOT use this skill for <near-neighbor> — see <other-skill>.

下書きを提示し、長さを測定します（python3 scripts/measure.py <path/to/SKILL.md> は、説明文の文字数、本文の行数、本文の推定トークン数を、それぞれの上限と比較して報告します）。調整を繰り返してください。

• ✅ 最初の50文字に、そのスキルならではの名詞を含める
• ✅ エージェントに向けた命令形の三人称で記述する。主語はスキルとし、「I」にしない
• ✅ ユーザーの実際のフレーズを、少なくとも1つ引用して含める
• ✅ 間接的な依頼も対象にする条項を含める（「X を明示的に言及していない場合でも」）。これは公式に推奨されています
• ✅ 近接分野がある場合は Do NOT use this skill for … を含める
• ❌ 一人称（「I help you create skills」）は、アクティベーションを低下させます（Seleznov n=650）
• ❌ 曖昧な表現（「スキルを作成するためのスキル」）や箇条書き形式の説明文は避けます。この形式を使っている調査対象の上位スキルはありません
• ❌ 強度を過剰に高める表現（「CRITICAL: you MUST invoke this」）は避けます。モデルは強い表現に反応して過剰に起動するため、公式の対処法は通常の語調を保つことです。起動率を高めるには、強い言い方ではなく、実際のトリガーをより多く含め、対象範囲を補足する条項を加えてください。

フェーズ 3 — Frontmatter

以下のフィールドをこの順序で出力し、スキルで必要な場合を除き、それ以外は出力しないでください。

---
name: <kebab-case, ≤64 chars, no "anthropic"/"claude" reserved words>
description: <string from Phase 2>
license: MIT
argument-hint: "[<short-token>]"    # top-level, not nested — and QUOTED: bare [x] is a YAML list, not a string
effort: high                        # optional Claude Code key; overrides the session level while the skill runs
metadata:
  author: <user-supplied>
  version: "1.0.0"
---

effort は種類ごとに次の値がデフォルトになります。自動化とリファレンスは low、技術系は medium、監査と方法論は high、複数ソースの統合とエージェント型コーディングは xhigh です。成果物が長いファイルになるスキルは high のままにしてください。xhigh／max では、モデルが推論時と出力時の2回、ファイルを作成するためです。省略するとキーを継承します。根拠とライブ検証に関する注記は FRONTMATTER.md に記載されています。

その他の任意フィールド、frontmatter のアンチパターン、および3段階の移植性ルールについては、references/FRONTMATTER.md を参照してください。

フェーズ 4 — 本文の内容

テンプレートの全容は references/PATTERNS.md にあります。本文を生成するときにのみ読み込んでください。このセクション一覧は rate-skill のカテゴリー4で評価される共通仕様です。2つのスキルで内容を一致させてください。

種類	必須	任意
方法論	概要、ワークフロー（フェーズごとに1つのタスク）、例、注意点	品質指標／アンチパターン
技術系	概要、クイックスタート／セットアップ（最小限のコードブロックを1つ）、クイックリファレンスまたは API の概要、例、注意点	トラブルシューティング — 長い API の概要は references/API.md に移す
監査	概要、ワークフロー、評価基準（シグナル → 重み → チェック）、出力形式、高品質／低品質な成果物の例、注意点	—
リファレンス	概要、ナビゲーション（読み込みタイミングの表）、注意点	主要概念 — SKILL.md はルーターのままにし、データをインラインで記述しない
自動化	概要、コマンド一覧表、実行例、失敗モード、注意点	トラブルシューティング — 実際のスクリプトは scripts/ に配置する

すべての種類に適用されるコンテンツルール：

• 必ず ## Gotchas を含めてください — 基本方針：「多くのスキルでは、最も価値の高い内容は注意点の一覧です。」注意点は SKILL.md に記載し、参照ファイルには移さないでください。状況に直面する前にエージェントが読む必要があるためです。デプロイ済みのスキルを使うエージェントに修正を加えるたびに、その内容を新しい注意点として追加してください。
• 注意点以外にも、公式な指示パターンが5つあります。出力形式のテンプレート（形式を文章で説明するより、具体的な構造のほうがエージェントはパターンを認識しやすいため）、複数ステップのワークフロー向けのチェックリスト、検証ループ（実行 → 検証 → 修正 → 繰り返し）、一括操作や破壊的操作向けの計画・検証・実行、実行のたびにエージェントが同じロジックを作り直すのを防ぐ同梱スクリプトです。すべてを使うのではなく、適したものを使ってください。
• 選択肢ではなくデフォルトを提示してください — 1つの方法を選び、代替案には簡単に触れてください。
• 宣言より手順を優先してください — 個別のケースで何を出力するかではなく、その種類の問題にどう取り組むかを教えてください。
• 「Xをしてはいけない」には、必ず代わりにすべきことを示してください。 公式方針：「Claude に何をしてはいけないかではなく、代わりに何をすべきかを伝えてください。」

エージェント型の調整 — これらは含めないでください。 モデルはすでにこれらを実行するため、指示を繰り返すと動作が強まり、品質が向上しないままトークンを消費します。

• 汎用的な自己再確認の手順は含めない — 「回答を再確認する」「応答する前に再検証する」「重要なタスクでは必ず最後に検証手順を追加する」といった記述は削除します。修正方法は言い換えではなく削除です。残すのは次の3つで、最後の2つは長時間にわたる作業で推奨されます。外部の状態に対するチェック（テストスイートを実行する、ファイルが解析できることを確認する、スキーマに照らして検証する）、新しいコンテキストのエージェントが別のエージェントの出力を評価する、ライター・ベリファイアパターン、進捗報告の前に行うエビデンス監査（「ツールの結果で示せる作業のみ報告する」）。問題なのは、エージェントが自分で生成した作業を、照合できる外部のものがないまま読み返すことです。
• エージェントに推論をそのまま出力するよう指示しない（「考えを示してください」「応答で推論を説明してください」） — reasoning_extraction による拒否やモデルのフォールバックを引き起こすことがあります。代わりに、結論と根拠を求めてください。
• エージェントに考えない、推論しないよう指示しない — 内部 XML タグが可視の出力に漏れる可能性が高まります。推論については何も言わず、出力の形を指定してください（「チャットは1行、成果物はファイル」）。
• ナレーションを抑制する指示（「すべての所見を最終応答まで保留する」「実況しない」「途中経過を報告しない」）や、書式を禁じる指示（「箇条書きは使わない」「見出しを付けない」「太字にしない」）は避けてください。どちらも、過剰なナレーションや書式設定をしていたモデル向けに書かれたものです。モデルの挙動は逆なので、こうした指示を入れると、応答がなくなったり、平板な文章になったりします。代わりに、具体的な更新や書式をいつ使うかを指定してください（「作業を割り振る前に範囲を報告する」「3項目以上を比較するときは表を使う」）。最終メッセージの形を指定すること（チャットは1行、成果物はファイル）には問題ありません。
• スキルでサブエージェントを使う場合は、委任の範囲を定める — サブエージェントを使うべき状況と上限を明記し、独立したエージェントは1つのメッセージで割り当て、それぞれの実行が終わるのを待たずに作業を続けてください。際限のない委任はコストを増大させ、完了まで待つ委任は経過時間を増大させます。
• スキルがファイルを書き出す場合は、成果物の範囲を定める — 出力テンプレートに「タスクに応じた長さにし、埋め草のセクション、重複する要約、定型文を入れない」といった一文を加えてください。書き出す成果物は、初期状態では長くなりがちです。
• 範囲の狭いスキルがどこで終わるかを明示する — モデルは自ら範囲を広げ、依頼されていない手順を追加する傾向があります。スキルがコードを生成する場合は、コードに関する次の一文も加えてください。「タスクで言及されていない既存のバグや挙動は、ここで修正せず、フォローアップとして報告する。テストをコミットするのは、タスクで求められている場合、またはリポジトリでこの種の変更に対するテストをすでに管理している場合に限り、周辺のテストファイルと同程度の規模にする。一時的なチェックはテストファイルではない。」この一文を加えると、タスクの成功率を変えることなく、依頼されていない追加作業やコミットされるテストコードを大幅に減らせます。
• ハーネスが注入する内容を繰り返さない — 自律性に関するブロック、作業の範囲を定めるブロック、進捗更新の一文、過剰な計画を促す記述への注意、非表示のツール出力に関する注意、ツール呼び出しのバッチ処理を促す記述、読みやすさのルールは、すべての Claude Code セッションにすでに含まれています。同じ内容を別の表現で繰り返すと、モデルは2つの指示をすり合わせる必要があります。

フェーズ5 — 例

同じ状況の言い換えではなく、異なる状況を扱う例を3〜5個作成します。エージェントが意図しないパターンを見出さないよう、例ごとに十分な違いを持たせてください。少なくとも1つは❌の反例にします。✅から始め、余裕があれば最後も✅で終えます（新近性バイアス）。各例に、1行の判定を付けます。

### Example: <one-line task>

✅ Desired

<short code or transcript>

Why it works: <one sentence>.

### Counter-example

❌ Anti-pattern

<short code or transcript>

Why it fails: <one sentence>.

品質ラベルには✅/❌を使ってください。調査したコミュニティ上位スキル8件のうち、<Good>/<Bad> の XML 形式は1件もありませんでした。これはラベルの話であり、XML の使用に関するものではありません。構造を区切る <example>/<examples> は公式に推奨されており、問題ありません。本文が300行を超えたら、これらを references/EXAMPLES.md に移し、そこに何が含まれているかを示す参照を付けます。これは採点の対象に全量が含まれます。

フェーズ6 — 注意点

一般的なスキル作成の助言ではなく、このスキル特有の失敗パターンを示します。各項目は、症状を1行、原因を1行、対処法を1行で記述します。

フェーズ 7 — 段階的開示の確認

scripts/measure.py で測定します。SKILL.md が 300 行を超えたら抽出します。合計 500 行／約 5,000 トークンの上限が、どちらの場合も厳しい上限です。

1. 抽出候補のセクションを大きい順に列挙します。
2. references/<TOPIC>.md ファイルを提案します。仕様で文書化されている名称は複数形ですが、ディレクトリ名を検証するものはありません。既存の単数形の reference/ ディレクトリを、表記を整えるためだけに改名してはいけません。
3. 抽出したファイルは、必ず 1 階層の深さにとどめます。それより深くネストすると、プレビュー読み取り時に黙って切り捨てられます。
4. それぞれについて、いつ読み込むか、何が記載されているかを示す 1 行のポインターを SKILL.md に記載します。例外として、注意点は残します。

フェーズ 8 — 評価セット（確定前に必須）

公式の説明最適化ループで使うセットを作成します。

1. 約 20 件のクエリ — 8〜10 件の トリガーすべきクエリ（フェーズ 1 の語句と、その言い換えや間接的な依頼）と、8〜10 件の トリガーすべきでないクエリ（フェーズ 1 の類似語句と無関係な作業）。
2. 学習用／検証用に 60／40 で分割し、両方の半分で比率を保ちます。1 回シャッフルしたら、以降の反復では分割を固定します。
3. references/EVAL.md に保存し、分割を明記して、プロトコルを記載します。各クエリを新しいセッションで約 3 回実行します。トリガー率は、スキルが呼び出された実行回数の割合です。トリガーすべきクエリは 0.5 超、トリガーすべきでないクエリは 0.5 未満で合格です。
4. 学習用データでの失敗だけを対象に反復します。表現を選ぶ際に検証用データを決してのぞき見してはいけません。その後、検証データで確認し、検証スコアが最も高いものを選択します。後半の反復では過学習が起きるため、前の草稿のほうが良い結果になることもあります。「通常は 5 回の反復で十分です」。
5. 確定前に、ユーザーに新しい Claude セッションで 3〜5 件のクエリをスポットチェックしてもらいます。

注意点（公式）：エージェントは単独で対応できる範囲を超えるタスクでもスキルを参照するため、非常に簡単なクエリでは、説明が完璧でもトリガーされないことがあります。そのようなクエリを理由に説明を何度も変更しないでください。

本文がトリガーされるだけでなく出力を改善するかどうかを測るには、公式の出力品質ループを実行します。スキルあり／なしで 2〜3 件のテストケースを実行し、最初の実行後に作成した、根拠が必要なアサーションで採点します。両方の設定で合格するアサーションは削除します。方法論や監査向けのスキルには有用ですが、小規模なリファレンススキルには過剰です。

出力レイアウト

<skill-name>/
├── SKILL.md                       # <300 lines, one job
├── references/                    # plural — load on demand
│   ├── PATTERNS.md                # optional: body templates by type
│   └── EVAL.md                    # train/validation eval set (Phase 8)
├── scripts/                       # optional: deterministic helpers (this skill bundles measure.py)
└── assets/                        # optional: templates copied into output

例

方法論と技術的な説明の✅／❌のペア、4 つの欠陥を逆にした反例、外部状態を確認する本文の手順と、エージェント自身の作業を再確認する手順：references/EXAMPLES.md。

落とし穴

• 症状： 新しいスキルが自動的に呼び出されません。 原因： 説明が曖昧で、具体的なトリガーがありません。 対処法： 「ユーザーが…を望んでいる場合は必ず使用する」という形式に書き換え、引用符で囲んだトリガーフレーズを3つ以上含めます。
• 症状： 単独では動作しますが、ユーザーが20個を超えるスキルをインストールすると動作しなくなります。 原因： 特徴的なトリガーが50文字目より後ろにあり、一覧表示の予算によって切り捨てられています。 対処法： 特徴的な名詞をdescriptionの先頭に移動します。
• 症状： 完全一致するフレーズには反応しますが、間接的な依頼（CSVスキルに対する「このデータファイルを整理して」など）を見逃します。 原因： 対応範囲を示す文言がありません。 対処法： 「Xが明示的に言及されていない場合でも」を追加します。
• 症状： 説明は訓練データで高いスコアを得ますが、検証データでは性能が低下します。 原因： 過学習です。各ラウンドで同じクエリに対して文言を調整しています。 対処法： 検証スコアで選択し、データ分割を固定します。前の反復のほうが優れている場合もあります。
• 症状： 読み込み時に「Unexpected key」警告が表示されます。 原因： トップレベルにversion、author、またはtagsがあります。 対処法： metadataの下に移動します。argument-hintとhooksはClaude Codeで有効なトップレベルキーなので、そのままにします。Anthropicのパッケージ検証ツールだけがこれらを拒否します。
• 症状： 1つのプロンプトに2つのスキルが反応します。 原因： トリガーが重複しており、対象外の範囲が指定されていません。 対処法： 適合しないほうにこのスキルをXに使用しないでください。Yを参照してくださいを追加します。
• 症状： SKILL.mdが700行あり、エージェントが誤ったセクションを引用します。 原因： 単一ファイルが肥大化しており、Claudeは先頭部分を読み、末尾を見落とします。 対処法： 1階層下のreferences/に切り出し、「…の場合に読み込む」という明示的な参照を追加します。

統合

• rate-skill — 生成後に実行して、結果を評価します。generate-skillが生成し、rate-skillが監査します。Phase 4の表とrate-skillのCategory 4の表は、共通の仕様です。