skill-creator

スキル作成

高品質なエージェントスキルを作成、評価、改善します。このスキルでは、スキルで何を実現するかの計画、SKILL.md と参照ファイルの作成、評価基準に基づく品質スコアの算出、本番環境の基準を満たすまでの改善という、ライフサイクル全体を扱います。

理念： 優れたスキルは、長さではなく正確さが重要です。説明によって適切なリクエストがスキルに振り分けられます。本文では、環境、ツールの契約、デフォルト設定、ドメインに関する判断、各制約の理由など、モデルがほかでは得られないコンテキストを示し、能力のあるモデルが自力で行えることは省きます。現在の Claude モデルは指示に忠実かつ文字どおりに従うため、すべての行が実行に反映されます。過剰に手順を指定したり、強い口調で指示したりすると、融通が利かず慎重すぎる出力になります。一方、明確な目標と品質基準を示せば、モデル自身が作業を計画できます。詳しくは references/writing-guide.md をご覧ください。

実行時の適応： 外部ツールを使用するスキルでは、実行時にインストール状況、認証状態、接続状況を検出して、単一の方法を前提とせずに適応する必要があります。実際に代替手段がある場合は、フォールバック経路を用意してください。パターンの一覧は references/dynamic-calling.md をご覧ください。

---

ステップ 1：ユーザーの要望を把握する

リクエストを次のいずれかのモードに分類します。

ユーザーの意図	モード	移動先
新しいスキルを一から作成する	作成	ステップ 2
既存のスキルを改善・修正する	改善	ステップ 6
スキルの品質を評価・採点する	評価	ステップ 7

意図が曖昧な場合は、「新しいスキルの作成、既存のスキルの改善、スキルの評価のどれを希望しますか？」と尋ねます。

要件を集める（作成モードの場合）

何かを書く前に、次の質問に回答します（不明点があればユーザーに尋ねます）。

質問	重要な理由
このスキルでどのようなタスクを自動化しますか？	中核となるワークフローを定義します
対象ユーザーは誰ですか？	複雑さや用語のレベルを決めます
どのツール、API、CLI を使用しますか？	依存関係とプラットフォームの制限を決めます
ユーザーはどのような入力を提供しますか？	パラメーターとデフォルト設定を定義します
出力はどのような形式にしますか？	出力の仕様を定義します
API キーや認証情報が必要ですか？	required_environment_variables を決めます
Claude.ai で動作させますか、それとも CLI 専用にしますか？	プラットフォームフィールドと動的コマンドを決めます

---

ステップ 2：スキルのアーキテクチャを計画する

SKILL.md を作成する前に、構成を計画します。各パターンの詳しい説明は references/architecture-patterns.md をご覧ください。

構造パターンを選ぶ

パターン	使用する場面	構成	例
線形	分岐のない単一のワークフロー	セットアップ → 取得 → 分析 → 回答	earnings-preview
ルーター	ひとつの枠組みのもとに複数のサブタスクがある	セットアップ + ルーティングテーブル + サブスキル	stock-correlation（4 つのサブスキル）、etf-premium
方法論	実際のゲートを備えた正式なドメインフレームワーク	順序付きのチェック。各チェックで分析を終了できる	sepa-strategy
ウィジェット	インタラクティブな UI 出力を生成する	抽出 → 計算 → 描画 → 説明	options-payoff
API ラッパー	多数のエンドポイントを持つ外部 API をラップする	認証 + エンドポイント一覧 + 詳細な参照情報	fintel-data

概要を計画する

すべてのスキルは次の 3 つの部分で構成されます。

1. セットアップ／検出 — 利用可能なツール、認証状態、実行環境を検出し、使用する方法を決定します。外部依存関係のないスキルでは、この部分を省略できます。
2. 作業内容 — 順序に実質的な意味がある番号付きの手順（計算前の取得、分析を終了できるゲートなど）と、モデルが行う判断を含めます。スクリプトのように手順を指定するのではなく、目標、基準、ドメインのヒューリスティックとして示します。
3. ユーザーへの回答 — 出力の仕様を示します。回答の冒頭に何を示すか、何を含めるか、どのような注意事項を適用するか、判定尺度があるかを明記します。

スキルに約 9 つを超える手順が必要な場合は、分割するかルーターパターンを使用します。

検出フローを計画する

外部ツールに触れるスキルでは、まず実行時の検出フローを実施します。すべてのパターンについては、references/dynamic-calling.md をお読みください。検出フローでは、次の点を確認します。

質問	検出方法	判断
CLI ツールはインストールされていますか？	command -v tool	CLI のパスか Python のフォールバックか
ユーザーは認証済みですか？	tool auth status / echo $API_KEY	認証設定を省略するか、手順を案内するか
ライブラリが使えるランタイムはどれですか？	ターミナルでの import lib と execute_code を比較	適切なランタイムに振り分ける
より高機能なツールは利用できますか？	gh --version と git --version を比較	高機能な方法か、最小限の方法か
ライブデータにアクセスできますか？	curl -s endpoint	ライブデータか、キャッシュ／デフォルトデータか

検出結果は、スキルの以降の部分で従う判断ツリーに反映されます。推測せずに確認してください。

参照ファイルを計画する

SKILL.md と references/ のどちらに記載するかを決めます。

SKILL.md（約250行以内）	references/
ワークフローと判断ポイント	詳細な API ドキュメント
振り分け／判断テーブル	コードテンプレート（20行超）
パラメーターのデフォルト値テーブル	数式とエッジケース
出力仕様	トラブルシューティング用データベース
簡単な例（1～3件）	包括的な例（4件以上）と日付付きデータセット

---

ステップ 3：SKILL.md を作成する

各セクションの詳しい書き方については、references/writing-guide.md をお読みください。YAML フィールドの全項目については、references/frontmatter-guide.md をお読みください。

主なルール

1. 最初にフロントマター：name（小文字とハイフンを使用し、最大64文字）とdescription（最大1024文字で、山かっこを含めない）は必須です。説明文は、すべてのリクエストに含まれるルーティング用テキストです。スキルの機能、対応するリクエストのカテゴリ、ユーザーが使う特徴的な語彙（メソッド、ツール、データ型、エンティティ）を記載し、関連するリクエストを扱う兄弟スキルも示してください。類義表現を並べるのではなく、意図のカテゴリを記載します。

2. 外部依存関係の検出フロー：フォールバック用センチネルを使った!command``プローブでツール、認証状態、ランタイムを検出し、その後、適切な方法に振り分けます。Codexなど、コマンドの前処理を行わないホスト向けには、同梱のコマンドをシェルツールで実行し、実際の出力を使うようエージェントに明示してください。実際に利用可能な代替手段がある場合は、2つ目の方法も提示します（CLI、Pythonライブラリ、組み込みツールなど）。references/dynamic-calling.mdを参照してください。

3. 具体性は脆弱性に合わせる：壊れやすい操作（インストール、認証、CLIの構文、APIの契約、正確さが求められる計算）には、正確なコマンド、フラグ、コードを記載します。判断を伴う作業（分析、解釈、執筆）では、目標、基準、分野固有のヒューリスティクスを示し、計画はモデルに任せます。チェックに失敗すると分析が本当に終了する箇所には、合否判定を設けます。

4. デフォルト値の表：ユーザーが省略する可能性のあるすべてのパラメーターについて、明示的なデフォルト値を示します。スキルが入力待ちで止まらないようにしてください。

5. 最終ステップの出力仕様：最初に何を示すか、回答に何を含めるか、どのような注意事項が適用されるか、判定や評価尺度があるかを定めます。形式そのものが重要な場合（スコアカード、ウィジェット、チェックリスト）に限り、セクションごとのテンプレートを指定します。長さは語数や文数ではなく、定性的に説明します。実在企業について架空の数値を使う例を記載する場合は、例示であることを明示します。

6. 平易な表現：各制約は、その理由とともに一度だけ記載します。大文字のMUST／NEVER／CRITICAL、繰り返しの警告、現在のモデルが通常従う指示（「徹底する」「段階的に考える」「回答を再確認する」など）は省きます。こうした表現は作業の質を高めるどころか、過剰な反応や確認を招きます。読み取り専用、取引の実行禁止、プライバシーなど、実際のポリシー上の制約は平易な言葉で記載します。

7. 変わりやすい情報は正確に扱う：可能であれば最新データを取得し、古くなる情報には日付を付け、日付付きのデータセットはreferences/に保管します。公開前に、現在のライブラリでAPI名とレスポンスの形式を検証します。

各パターンの注釈付き例については、references/skill-examples.mdを参照してください。

---

ステップ4：参照ファイルを作成する

参照ファイルの作成ガイド全編については、references/writing-guide.mdを読んでください。

主なルール

1. 命名：lowercase-hyphenated.mdを使用し、概念のまとまりごとに1ファイル作成します
2. サイズ：クイックリファレンスは50～150行、詳細ガイドは150～400行、カタログは400～900行です
3. 構成：H1のタイトル、H2のセクション、コードブロック、表を含め、末尾にエッジケースのセクションを設けます
4. リンク：SKILL.mdの手順ではバッククォート付きのパスを使用し、末尾に## Reference Filesセクションを設けます

---

ステップ5：納品前に品質を確認する

references/quality-rubric.mdの品質基準に沿ってスキルを確認し、各評価項目を採点します。

クイックチェックリスト

• フロントマターに name と description があり、説明文は山括弧を含まず、1024文字未満です
• 説明文では、スキルの機能、対応する意図のカテゴリ、特徴的な用語を示しています。類義語に近い言い回しを列挙してはいません
• 該当する場合、近接する依頼に対応する関連スキルを説明文で案内しています
• SKILL.md は300行未満です（できれば250行未満）
• すべてのパラメーターに明示的なデフォルト値があります
• 順序が重要な箇所では番号付きの手順を使い、判断を伴う作業は目標、基準、ヒューリスティックとして示しています
• ゲートによって分析を中断するのは、チェックに失敗すると本当に先へ進めない場合だけです
• 最終ステップに出力の契約を記載しています。冒頭に示す内容、必須コンテンツ、注意事項、判定尺度を含めます
• 数値による長さの上限はありません。例には説明用であることを明記しています
• 制約は理由とともに平易な言葉で一度だけ記載しています。大文字の MUST／NEVER、「think step by step」や「double-check」といった定型文は使っていません
• 複雑な内容はインラインではなく、参照ファイルに記載しています
• 参照ファイルへのポインターにはバッククォート付きのパスを使っています
• 外部依存関係は実行時に !command`` チェックとフォールバック（|| echo "..."）で検出しています
• 別々のランタイムは別の環境として扱っています（terminal と execute_code）
• 適切な場合、法的／倫理的な免責事項を含めています
• 古くなるハードコードされたティッカー一覧、ツールのパス、日付のない静的データはありません
• スキル内の API 名、フィールド、コードは、現在のライブラリに照らして確認済みです

項目に不備がある場合は、ユーザーに提供する前に修正してください。

---

ステップ 6：既存のスキルを改善する

ユーザーからスキルの改善を求められた場合：

6a：現在のスキルを読む

SKILL.md とすべての参照ファイルを読みます（Hermes では skill_view(name) で読み込めます）。

6b：評価基準に照らして採点する

references/quality-rubric.md の品質評価基準を使います。採点の内訳をユーザーに示します（例）：

項目	スコア	課題
トリガーの品質	6/10	類義語に近い言い回しが20個あり、ETF のユースケースを見落としています
デフォルト値の網羅性	3/10	デフォルト値の一覧がありません
指示の設計	5/10	判断を伴う作業を手順化し、大文字の警告を使っています
出力の契約	4/10	架空の数値を含む、固定された9セクションのテンプレートです
参照ファイルの活用	7/10	構成の分割は適切ですが、トラブルシューティングが不足しています

6c：具体的な改善案を提案する

影響の大きい順に、具体的な変更を列挙します：

1. ［最優先］すべてのパラメーターを網羅するデフォルト値の一覧を追加する
2. ［優先度：高］意図のカテゴリと特徴的な用語を軸に、説明文を書き直す
3. ［優先度：中］固定レポートテンプレートを出力の契約に置き換える
4. ...

6d：変更を適用する

ユーザーの承認後、スキルファイルを編集します（Hermes では、対象を絞った変更には skill_manage(action='patch', ...) を、全面的な書き換えには skill_manage(action='edit', ...) を使います）。

---

ステップ 7：スキルを評価する

ユーザーからスキルの評価または採点を求められた場合：

7a：読み込んで分析する

SKILL.md とすべての参照ファイルを読みます。行数、手順数、デフォルト値の数、参照ファイル数を数え、説明文の長さと対応する意図のカテゴリを確認します。

7b：評価基準に照らして採点する

references/quality-rubric.md にある包括的な評価基準を使います。10項目それぞれを1～10点で採点します。

7c：評価表を提示する

## Skill Quality Scorecard: [skill-name]

| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | 8/10 | Covers all four intent categories; one sibling boundary missing |
| 2 | Defaults coverage | 9/10 | All 11 parameters have defaults |
| 3 | Instruction design | 8/10 | Ordered setup and compute; analysis stated as criteria |
| 4 | Reference file strategy | 7/10 | 2 files, could use troubleshooting |
| 5 | Dynamic content | 10/10 | Dep check + live data injection |
| 6 | Output contract | 9/10 | Leads with verdict; required caveats; scale defined |
| 7 | Error handling | 6/10 | Missing data handling unclear |
| 8 | Code/formula quality | 8/10 | Working JS, copy-paste ready |
| 9 | Conciseness & register | 7/10 | 196 lines; two capitalized warnings to restate |
| 10 | Domain accuracy | 9/10 | BS formulas correct, edge cases covered |

**Overall: 81/100** -- Production quality

### Top 3 Improvements
1. ...
2. ...
3. ...

参考スキル

このリポジトリにある、各パターンの参考になるスキル：

スキル	特に参考になる点
sepa-strategy	方法論のパターン：実効性のあるゲート、参照ファイル内のドメイン基準、判定尺度
options-payoff	ウィジェットのパターン：すべてのフィールドのデフォルト値、ライブデータの注入、明確な描画仕様
stock-correlation	ルーターのパターン：意図のルーティング表、自己完結型のサブスキル、コードで計算する指標
earnings-preview	出力の契約：コンテンツのチェックリスト、1つの判断セクション、要点から始める指針
fintel-data	API ラッパー：キー解決フロー、エンドポイント一覧、エラーの扱い

---

ステップ 8：ユーザーに応答する

Create モードの場合

以下を提出します：

1. SKILL.md の完全な内容
2. すべての参照ファイル
3. スキルディレクトリの README.md
4. 品質スコアカード（ステップ 5 のもの）
5. 推奨される次のステップ（テスト、反復、公開）

Improve モードの場合

以下を提出します：

1. 改善前と改善後の品質スコア
2. 実施した変更の概要
3. 今後改善できる点

Evaluate モードの場合

以下を提出します：

1. 品質スコアカードの全項目
2. 参照スキルとの比較
3. 優先順位を付けた改善項目

---

Reference Files

• references/dynamic-calling.md -- 中核となる参照資料：本番環境のスキルからの注釈付きの例を用いて、検出フロー、判断ツリー、メソッドのフォールバック、ランタイムの把握、複数ツールへの適応パターンを解説します
• references/writing-guide.md -- 現行の Claude モデル向けに SKILL.md の各セクションを作成する方法：説明、検出フロー、脆弱性に応じた指示、デフォルト、出力契約、参照ファイル
• references/architecture-patterns.md -- Linear、Router、Methodology、Widget、API Wrapper のパターンと、例およびアンチパターン
• references/frontmatter-guide.md -- YAML フロントマターのフィールド（name、description、platform、環境変数、config、credentials）の完全なリファレンス
• references/quality-rubric.md -- 1～10 の評価尺度、例、スコアの解釈を含む、10 項目の評価基準
• references/skill-examples.md -- 特定のパターンが有効な理由を示す、優れたスキルからの注釈付き抜粋