skill-creator

スキル作成

新しいスキルの作成と、反復的な改善を支援するスキルです。

ユーザーが作成プロセスのどの段階にいるかを見極め、それに応じて対応します。ゼロからスキルを定義する支援が必要な場合もあれば、すでにドラフトがあり、すぐに評価や反復改善に進みたい場合もあります。柔軟に対応してください。ユーザーが正式な評価を省略して会話を通じて反復改善したい場合は、それでも問題ありません。スキルが完成したら、トリガーの精度を高めるために、説明の最適化を実施するか尋ねてください。

---

ユーザーとのコミュニケーション

ユーザーの技術的な知識は幅広く異なります。「評価」や「ベンチマーク」は一般にそのまま使って問題ありませんが、「JSON」や「アサーション」は、ユーザーから明確な合図があるまでは、定義せずに使わないでください。迷ったら、簡単な説明を添えてください。

---

スキルの作成

意図を把握する

まず、ユーザーの意図を理解します。現在の会話に、ユーザーがスキルとしてまとめたいワークフロー（たとえば、「これをスキルにして」と依頼している場合）がすでに含まれていることがあります。その場合は、まず会話履歴から、使用したツール、手順、ユーザーによる修正、確認できた入出力形式を抽出します。ユーザーに不足分を補ってもらい、次のステップに進む前に確認を取ってください。

1. このスキルでClaudeに何ができるようになるべきですか？
2. どのようなときにこのスキルを起動すべきですか？（どのようなユーザーの表現や状況が該当しますか？）
3. 期待される出力形式は何ですか？
4. スキルが機能することを確認するため、テストケースを用意しますか？客観的に検証できる出力（ファイル変換、データ抽出、コード生成、固定の手順など）を扱うスキルでは、テストケースが役立ちます。主観的な出力（文章のスタイル、アートなど）を扱うスキルでは、通常は必要ありません。スキルの種類に応じて適切な初期案を提案しますが、最終的にはユーザーに選んでもらってください。

ヒアリングと調査

エッジケース、入出力形式、サンプルファイル、成功基準、依存関係について、積極的に質問してください。テスト用のプロンプトを書くのは、これらが明確になってからにしてください。

利用可能な MCP を確認します。調査（ドキュメントの検索、類似スキルの発見、ベストプラクティスの確認）に役立つ場合は、利用できればサブエージェントで並行して調査し、そうでなければその場で調査します。ユーザーの負担を減らせるよう、事前に必要な情報を集めてください。

SKILL.md を作成する

ユーザーへのヒアリングをもとに、次の要素を記入します。

• name：スキルの識別子（ケバブケース）
• description：主なトリガーとなる仕組みです。スキルの機能と、使用すべき具体的な状況を含めてください。「いつ使うか」に関する情報はすべてここに記載し、本文には入れないでください。Claudeがスキルを起動しない傾向を補うため、説明はやや積極的な表現にします。「ダッシュボードの作成方法」ではなく、「ダッシュボードの作成方法。ユーザーがダッシュボードやデータの可視化に言及したとき、あるいは『ダッシュボード』とはっきり依頼していなくても、社内データを表示したいと考えているときは、必ずこのスキルを使用してください」のように記述してください。
• license：MIT（常に）
• その他のスキルの内容 :)

スキル作成ガイド

スキルの構成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description, license required — nothing else)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

段階的な情報開示

読み込みレベルは3つあります。メタデータ（常にコンテキストに含まれる約100語）、SKILL.md 本文（スキルの起動時にコンテキストに含まれる。理想的には500行未満）、バンドルされたリソース（必要に応じて読み込む。容量制限なし）です。SKILL.md は500行未満に収めてください。上限に近づいている場合は、内容を references/ に移し、参照先を明記します。約300行を超える参照ファイルには、目次を追加してください。

ドメイン別の構成：スキルが複数のドメインやフレームワークに対応する場合は、バリエーションごとに整理します。

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claudeは、関連する参照ファイルのみを読み込みます。

記述パターン

指示には命令形を使います。出力形式は、明示的なテンプレートブロックを使って定義します（例：必ず次の正確なテンプレートを使用してください：...）。変換内容が具体的な場合は、入力：／出力：のペアで例を示します。

文体

強い口調で「必ず」と命じるのではなく、なぜ重要なのかを説明してください。スキルは汎用的なものにし、テスト例だけに特化させないでください。ドラフトを書いたら、仕上げる前に新鮮な視点で読み直してください。

テストケース

スキルのドラフトを書いたら、現実的なテストプロンプトを2～3個考えてください。実際のユーザーが使いそうなものにします。ユーザーに「試してみたいテストケースをいくつか挙げます。内容は適切ですか？追加したいものはありますか？」と伝えてから、実行します。

テストケースは evals/evals.json に保存します。現時点ではプロンプトだけを記載し、アサーションは追加しません。アサーションフィールドを含むスキーマ全体については references/schemas.md を参照してください。このフィールドはステップ2で追加します。

---

テストケースの実行と評価

このセクションは一連の作業です。途中で止めないでください。/skill-test やその他のテスト用スキルは使用しないでください。

結果は、スキルディレクトリと同じ階層にある <skill-name>-workspace/ に保存します。ワークスペース内では、イテレーションごとに整理します（iteration-1/、iteration-2/ など）。さらにその中に、各テストケースのディレクトリ（eval-0/、eval-1/ など）を作成します。これらを最初にすべて作成せず、必要に応じて作成してください。

ステップ1：すべての実行を同じターンで開始する（スキルあり、ベースライン）

各テストケースについて、同じターンで2つのサブエージェントを起動します。1つはスキルあり、もう1つはスキルなしです。これは重要です。スキルありの実行を先に起動して、後からベースラインに戻るのではなく、すべてを一度に起動し、ほぼ同時に完了するようにしてください。

スキルありの実行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

ベースラインの実行（同じプロンプトを使いますが、ベースラインは状況によって異なります）：

• 新しいスキルを作成する場合：スキルは一切使用しません。同じプロンプトを使い、スキルパスは指定せず、without_skill/outputs/ に保存します。
• 既存のスキルを改善する場合：古いバージョンを使います。編集する前に、スキルのスナップショットを作成して（cp -r <skill-path> <workspace>/skill-snapshot/）、ベースラインのサブエージェントにそのスナップショットを指定します。old_skill/outputs/ に保存します。

各テストケースについて、eval_metadata.json を作成します（現時点ではアサーションは空でかまいません）。各評価には、テスト内容がわかる説明的な名前を付けてください。「eval-0」のような名前だけにしないでください。この名前をディレクトリにも使います。このイテレーションで新規または変更した評価プロンプトを使う場合、新しい評価ディレクトリごとに次のファイルを作成してください。前のイテレーションから引き継がれるとは限りません。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

ステップ2：実行中にアサーションを作成する

実行が完了するのをただ待つのではなく、この時間を有効に使ってください。各テストケースの定量的なアサーションを作成し、内容をユーザーに説明します。evals/evals.json にすでにアサーションがある場合は、確認して何を検証するのか説明してください。

適切なアサーションは客観的に検証でき、説明的な名前が付いているものです。ベンチマークビューアーをざっと見ただけでも、各アサーションが何を確認するのかすぐにわかるようにしてください。文章のスタイルやデザインの品質といった主観的なスキルは、定性的に評価するほうが適しています。人の判断が必要なものに、無理にアサーションを当てはめないでください。

アサーションを作成したら、eval_metadata.json と evals/evals.json を更新します。

ステップ3：実行完了に応じて時間データを記録する

各サブエージェントのタスクが完了すると、total_tokens と duration_ms を含む通知が届きます。このデータをすぐに実行ディレクトリの timing.json に保存してください。

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

このデータを記録できる機会はこの一度きりです。データはタスクの通知経由で届き、ほかの場所には保存されません。通知をまとめて処理しようとせず、届いたものから順に処理してください。

ステップ 4：採点し、集約して、ビューアーを起動する

すべての実行が完了したら、次の手順に進みます。

1. 各実行を採点する — 採点用サブエージェントを起動する（またはインラインで採点する）か、agents/grader.md を読み込んで、各アサーションを出力と照らし合わせて評価します。結果は各実行ディレクトリの grading.json に保存します。grading.json の expectations 配列では、フィールドに text、passed、evidence を使用してください（name／met／details やその他の形式ではありません）。ビューアーはこれらの正確なフィールド名に依存します。プログラムで確認できるアサーションについては、目視で判断するのではなく、スクリプトを作成して実行してください。スクリプトはより速く、信頼性が高く、反復して再利用できます。

2. ベンチマークに集約する — skill-creator ディレクトリから集約スクリプトを実行します。

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   各構成について、合格率、時間、トークン数を含む benchmark.json と benchmark.md が生成されます。平均値 ± 標準偏差と差分も含まれます。benchmark.json を手動で生成する場合は、ビューアーが想定する正確なスキーマについて references/schemas.md を参照してください。 各 with_skill バージョンは、対応するベースラインより前に配置してください。

3. 分析者の視点で確認する — ベンチマークデータを読み、集計統計では見えにくい傾向を明らかにします。確認すべき点については、agents/analyzer.md の「ベンチマーク結果の分析」セクションを参照してください。たとえば、スキルに関係なく常に合格するアサーション（識別力がないもの）、ばらつきの大きい評価（不安定な可能性があるもの）、時間とトークン数のトレードオフなどです。

4. 定性的な出力と定量データの両方を使ってビューアーを起動する：

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   イテレーション 2 以降では、--previous-workspace <workspace>/iteration-<N-1> も渡してください。

   ヘッドレス環境の場合： webbrowser.open() が利用できない場合や、環境にディスプレイがない場合は、サーバーを起動する代わりに --static <output_path> を使ってスタンドアロンの HTML ファイルを出力してください。ユーザーが「すべてのレビューを送信」をクリックすると、フィードバックが feedback.json ファイルとしてダウンロードされます。ダウンロード後、次のイテレーションで使用できるように、feedback.json をワークスペースディレクトリにコピーしてください。

   注意：ビューアーの作成には generate_review.py を使用してください。カスタム HTML を作成する必要はありません。

5. ユーザーに伝える — ビューアーが開いていることを伝え、レビューが終わったら戻ってくるよう依頼します。

ステップ 5：フィードバックを読む

ユーザーから完了の連絡があったら、feedback.json を読み込みます。

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

フィードバックが空の場合、ユーザーは問題ないと判断したことを意味します。ユーザーから具体的な指摘があったテストケースを中心に改善してください。

作業が終わったら、ビューアーのサーバーを停止します。

kill $VIEWER_PID 2>/dev/null

---

スキルを改善する

改善の考え方

• 過剰適合ではなく、一般化する。 スキルはテストケースだけでなく、今後のさまざまなプロンプトでも機能する必要があります。解決しにくい問題が現れた場合は、厳格な制約を追加するのではなく、異なる比喩やパターンを試してください。
• プロンプトは簡潔に保つ。 出力だけでなく、トランスクリプトも読み、非生産的な作業につながる内容を削除します。常に大文字で ALWAYS や NEVER と書きたくなったら、推論を促す表現に変えてください。LLM は厳格なルールよりも、その理由を理解するほうがうまく対応します。
• 理由を説明する。 適切な判断を下せるだけの背景情報をモデルに与えます。要件そのものだけでなく、その根拠も示してください。
• 繰り返しの作業をまとめる。 複数のテストケースのトランスクリプトで同じヘルパースクリプトが個別に作成されていた場合は、それを scripts/ にまとめ、スキルで使うよう指示してください。

イテレーションループ

スキルを改善した後は、次の手順を実行します。

1. 改善内容をスキルに適用します
2. ベースラインの実行も含め、すべてのテストケースを新しい iteration-<N+1>/ ディレクトリに再実行します。新しいスキルを作成する場合、ベースラインは常に without_skill（スキルなし）です。これはすべてのイテレーションで変わりません。既存のスキルを改善する場合は、ベースラインとしてユーザーが最初に持ち込んだ元のバージョンと前回のイテレーションのどちらを使うか、適宜判断します。
3. 前回のイテレーションを指す --previous-workspace を指定してレビュアーを起動します
4. ユーザーがレビューを終えたと伝えるまで待ちます
5. 新しいフィードバックを読み、再度改善を繰り返します

次のいずれかに当てはまるまで続けます。

• ユーザーが満足したと言う
• フィードバックがすべて空である（すべて問題なし）
• 意味のある進展が見られなくなる

---

上級編：ブラインド比較

2つのスキルのバージョンをより厳密に比較したい場合（たとえば、ユーザーから「新しいバージョンは本当に良くなったのか」と尋ねられた場合）は、ブラインド比較システムを利用できます。詳細は agents/comparator.md と agents/analyzer.md を参照してください。基本的には、2つの出力をどちらがどのバージョンかを伏せて独立したエージェントに提示し、品質を判定してもらいます。その後、勝った理由を分析します。

これは任意で、サブエージェントが必要です。ほとんどのユーザーには不要です。通常は人によるレビューで十分です。

---

説明文の最適化

スキルを作成または改善した後、トリガー精度を高めるために説明文を最適化することを提案します。

ステップ 1：トリガー評価クエリを生成する

「トリガーすべき」と「トリガーすべきでない」を混在させた評価クエリを20件作成し、JSON として保存します。

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

ファイルパス、企業名、くだけた表現、誤字、さまざまな長さなどを含め、現実的で具体的なクエリを作成します。エッジケースを重視してください。"Format this data" のような抽象的な依頼は避けます。

トリガーすべきクエリ（8～10件）では、表現を変化させます（フォーマルなもの、くだけたもの）。ユーザーがスキル名を挙げていなくても明らかにそのスキルが必要なケースや、競合するスキルよりこのスキルを優先すべきケースも含めます。

トリガーすべきでないクエリ（8～10件）では、ニアミスに焦点を当てます。キーワードは共通していても、別の対応が必要なクエリにします。明らかに無関係な否定例は避けてください。否定例も、実際に判断が難しいものにします。

ステップ 2：ユーザーにレビューしてもらう

HTML テンプレートを使って、評価セットをユーザーに提示します。

1. assets/eval_review.html からテンプレートを読み取ります
2. プレースホルダーを置き換えます。
   • __EVAL_DATA_PLACEHOLDER__ → 評価項目の JSON 配列（JS 変数への代入なので、前後を引用符で囲まないでください）
   • __SKILL_NAME_PLACEHOLDER__ → スキル名
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → 現在のスキルの説明文
3. 一時ファイル（例：/tmp/eval_review_<skill-name>.html）に書き込み、開きます：open /tmp/eval_review_<skill-name>.html
4. ユーザーはクエリの編集、「トリガーすべき」の切り替え、項目の追加や削除を行い、「Export Eval Set」をクリックできます
5. ファイルは ~/Downloads/eval_set.json にダウンロードされます。複数ある場合（例：eval_set (1).json）、Downloads フォルダーで最も新しいものを確認します。

このステップは重要です。評価クエリの質が低いと、説明文の質も低くなります。

ステップ 3：最適化ループを実行する

評価セットをワークスペースに保存し、ユーザーに数分かかることを伝えてから、バックグラウンドで実行します。

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

トリガーテストがユーザーの実際の利用体験と一致するよう、システムプロンプトにあるモデル ID（現在のセッションで動作しているもの）を使用します。

実行中は定期的に出力を確認し、何回目のイテレーションか、スコアがどうなっているかをユーザーに知らせます。

スクリプトはループ全体を自動で実行します。60/40 の学習／テスト分割、信頼性を高めるクエリごとの3回実行、Claude が提案する改善の最大5回のイテレーション、ブラウザー上の HTML レポートが含まれます。また、過学習を避けるため、学習スコアではなくテストスコアに基づいて選ばれた best_description を返します。

ステップ 4：結果を適用する

JSON 出力から best_description を取得し、スキルの SKILL.md のフロントマターを更新します。変更前と変更後をユーザーに示し、スコアを報告します。

---

パッケージ化して提示する（present_files ツールが利用可能な場合のみ）

present_files ツールにアクセスできるか確認します。利用できない場合は、このステップをスキップします。利用できる場合は、スキルをパッケージ化し、.skill ファイルをユーザーに提示します。

python -m scripts.package_skill <path/to/skill-folder>

パッケージ化した後、インストールできるよう、生成された .skill ファイルのパスをユーザーに伝えます。

---

Claude Code 固有の手順

Claude Code では、サブエージェント、評価ビューアーのブラウザー起動、claude -p による説明の最適化ループを含め、コアのワークフローをすべて実行できます。

claude-superskills のスキル出力先：

claude-superskills パッケージに追加するスキルを作成する場合は、skills/<skill-name>/ に配置します。プラットフォームディレクトリ（.github/skills/、.claude/skills/、.codex/skills/ など）は、このリポジトリではすべて gitignore 対象であり、空のままにする必要があるため、配置しないでください。すべてのルールについては、references/claude-superskills-conventions.md を参照してください。

claude-superskills 用のスキルを作成した後：

1. 適切なバンドルの bundles.json にスキルを追加します
2. README.md のスキル表にスキルを追加し、スキルバッジの件数を増やします
3. CLAUDE.md のアーキテクチャツリーと Skill Types セクションを更新します
4. node scripts/release.js patch を実行し、5 つすべてのバージョンファイルをまとめて更新します

---

Claude.ai 固有の手順

Claude.ai にはサブエージェントがないため、次のように対応します。テストケースは自分で順番に実行します（ベースラインなし、並列実行なし）。ブラウザーレビュアーは起動せず、結果を会話内に提示します。定量的なベンチマーク、説明の最適化（claude -p が必要）、ブラインド比較はスキップします。ドラフト → テスト → フィードバック → 改善というコアのループは引き続き実行できます。package_skill.py によるパッケージ化は、Python があればどこでも実行できます。

---

参考ファイル

• agents/grader.md — 出力に対するアサーションを評価します
• agents/comparator.md — 2 つの出力をブラインド A/B 比較します
• agents/analyzer.md — どちらかのバージョンが優れていた理由を分析します
• references/schemas.md — evals.json、grading.json、benchmark.json の JSON スキーマ
• references/claude-superskills-conventions.md — claude-superskills へのコントリビューションルール

---

自分で入力を評価する前に、評価ビューアーを生成してください。人間ができるだけ早く出力を確認できるようにします。