fable-skill-creator

Skill Creator

エージェントの動作をプレッシャー下で変える Skill を作成します。優れた実践を説明するだけの Skill は作成しません。

ミッション

本番環境で使える Skill は、繰り返し発生する判断を扱う簡潔な運用マニュアルです。エージェントが状況を認識し、妥当な選択肢から行動を選び、適切な証拠を集め、魅力的でも安易な近道を退け、別の専門家に任せるほうが適切な場合に円滑に引き継げるようにします。

スキーマに準拠した SKILL.md だけでは不十分です。「調査、計画、実装、検証」とだけ記す Skill は、行動能力ではなくドキュメントです。

発動条件

以下の作業を依頼された場合に、この Skill を使用します。

• 再利用可能な新しい Skill を作成する。
• 既存の Skill を強化またはリファクタリングする。
• 発動精度を高める、または隣接する Skill との重複を減らす。
• リファレンス、例、テンプレート、エージェント、または評価を追加する。
• 繰り返し行われるワークフローを、持ち運び可能なエージェント機能に変換する。
• ハッピーパスの例だけでなく、さまざまな状況で Skill が正しく動作することを証明する。

通常のアプリケーション変更、バグ修正、リポジトリの保守には使用しないでください。それらは適切なライフサイクル Skill に振り分けてください。

入力

• user_intent：組み込む機能、動作、またはワークフロー。
• workflow_trace：利用可能な場合、観察された判断、ツール、失敗の順序。
• reference_sources：一次資料、スキーマ、ドメインルール、または実証済みの内部パターン。

Skill の深度分類

作成に着手する前に、機能を分類します。

分類	典型的な形態	必要な深度
ルール	分岐が少ない、安定した単一の判断	明確な境界を持つ簡潔な Skill
手順	複数段階からなる反復可能な操作	段階的なプロトコルと証拠
診断	症状から複数の原因を見分ける	失敗の分類と反証
オーケストレーター	専門家を選択または委任する	ルーティング表と引き継ぎの契約
ドメインエキスパート	相当量の専門知識を要する	詳細なリファレンス、例、評価ファミリー

診断、オーケストレーター、またはドメインエキスパートに分類される機能では、短いチェックリストだけでは不十分と考えてください。

Skill の契約 V2

重要な Skill では、以下の問いに明示的に答える必要があります。

1. いつ発動するか

発動条件、発動しない条件、前提条件、エスカレーション条件を定義します。この Skill を選択すべきでない、近接するタスクも含めます。

2. エージェントはどのような状況にあるか

動作を変える簡潔な分類を示します。例：範囲が限定されているか、アーキテクチャに関わるか。決定論的か、不安定か。ローカルか、外部か。取り消し可能か、破壊的か。既知か、不確実か。

3. どのような判断が必要か

曖昧なケースでは、判断表または分岐ルールを使います。「適切な場合」のような曖昧な表現の背後に判断を隠さず、どのような証拠があれば適切と判断できるかを定義します。

4. 実行プロトコルは何か

各段階について、以下を指定します。

• 目的。
• 許可される行動。
• 必要な証拠。
• 終了条件。
• 停止条件またはエスカレーション条件。

5. どのような失敗が起こりうるか

ドメイン固有の失敗クラスと、それらを区別する観測可能な兆候を示します。あらゆる失敗を「再試行」や「復旧を使う」にまとめないでください。

6. 何を決して偽にしてはならないか

Skill の実行中に常に維持すべき不変条件を列挙します。例：有効な RED の前に本番環境を変更しない。レジストリで確認する前にリリース済みと主張しない。具体的な失敗モードを示さずにレビュー指摘を行わない。

7. どのような近道が魅力的でも無効か

時間的なプレッシャーや曖昧な依頼のもとで、優れたモデルが選びがちなアンチパターンを記録します。

8. Skill からどのような証拠を引き継ぐか

次の専門家に渡すためのパケットを定義します。学んだ事実、実行したコマンド、変更した成果物、残存リスク、未解決の疑問、必要に応じて証拠の鮮度を含めます。

9. 段階的なリソースには何を含めるべきですか？

SKILL.mdには判断ロジックを記載します。リファレンスには、同じチェックリストを別の言い回しで繰り返すのではなく、運用面の詳しい情報を追加します。

役立つリソースの例：

• 判断のヒューリスティクス；
• 障害の診断ガイド；
• レガシー環境やエッジケース向けのプレイブック；
• トレードオフを示す具体例；
• ツールに依存しない検証方法；
• チェックリストに、一般には知られていないドメイン知識が盛り込まれている場合に限ったチェックリスト。

10. Skillが実際に機能することをどう確認しますか？

意味的に異なる評価ファミリーを複数作成します。1つのシナリオの表面的なバリエーションは、十分な幅とはみなしません。

評価の深さの基準

重要度の高いSkillでは、評価の網羅性が成熟したと判断する前に、パッケージ全体で少なくとも6つの意味的なシナリオファミリーを目指します。ファミリーとは、同じプロンプトを5通りに書き換えたものではなく、異なる判断問題です。

次のようなケースを組み合わせて含めます：

• 明確に起動すべきケース；
• 境界ケース／起動すべきでないケース；
• 分類が必要な曖昧な状況；
• 近道を取るよう迫る敵対的なケース；
• 不完全な証拠や矛盾する証拠があるケース；
• 失敗からの復旧や引き継ぎ；
• 通常の正常系の手順が使えないレガシー環境または制約のある環境。

エンタープライズ向けの動作ハーネスでは、各ファミリーを既知／否定的／曖昧／敵対的／ホールドアウトのバリエーションへさらに展開できます。ただし、その展開を意味的なファミリーの幅の代わりにすることはできません。

作成手順

1. 実際の作業を観察する：実際のワークフローや一次資料から、判断、成果物、失敗モード、引き継ぎを特定します。
2. 隣接するSkillを整理する：このSkillが担当する範囲と、意図的に対象外とする範囲を定義します。
3. 重要で失敗しやすい判断について、まず評価シナリオを書く：期待される行動を明確に記述できない場合、Skillの契約はまだ整っていません。
4. 判断モデルを設計する：分類、分岐、不変条件、停止条件を定めます。
5. ツールに依存しない命令形の言葉でSKILL.mdを書く。
6. メインのSkillが煩雑になるほどの詳細は、段階的なリソースとして追加します。
7. ひと目で明らかな最初の一手が誤りとなるケースを少なくとも1つ含め、具体例を追加します。
8. ホスト向けプロンプトがSkillの契約全体を参照するように、エージェントプロファイルを作成または更新します。1行の要約でSkillを置き換えてはいけません。
9. パッケージングとレジストリのメタデータを検証します。
10. 決定論的評価と動作評価を実行します。Skillまたは評価コーパスのハッシュが変わった場合は、新たな検証が必要です。

不変条件

• Skillの変更後、成熟度ラベルを維持するために評価のしきい値を下げてはいけません。
• プライベートな期待値または禁止事項を示すオラクルのフィールドを、プロバイダーに表示されるプロンプトへコピーしてはいけません。
• 正規のSkillでは、プロバイダーに依存しない言葉で機能を記述する必要があります。
• 重要度の高いSkillパッケージには、十分な分量の段階的なリファレンス（1000バイト以上）を少なくとも1つ含める必要があります。
• 動作面での成熟度を主張するには、意味的なシナリオファミリー全体にわたるホールドアウト評価を新たに実施し、検証済みであることが必要です。

判断ルール

• 重複する小規模なSkillをいくつも作るより、対象領域が明確な強力なSkillを1つ作ることを優先します。
• 通常の同じ依頼に対して2つのSkillがどちらも起動し得る場合、キーワードを追加する前に、それぞれの境界を明確にします。
• 本文が正常系の手順を順番に並べただけなら、実際の作業で専門家が選択を迫られる分岐を追加します。
• リファレンスが本文の言い換えにすぎない場合は、より詳細な内容に置き換えます。
• Skillの説明を繰り返すだけで合格できてしまう評価には、曖昧さや矛盾する証拠を追加します。
• Skillの変更後、成熟度ラベルを維持するために評価のしきい値を下げてはいけません。
• プライベートな期待値または禁止事項を示すオラクルのフィールドを、プロバイダーに表示されるプロンプトへコピーしてはいけません。
• 正規の動作にプロバイダー固有のツール名を使うのは避けます。機能を記述し、ホストアダプターで対応付けるようにします。

失敗の分類

起動の失敗

Skillが頻繁に起動しすぎる、または明らかな依頼を見逃します。手順の説明を追加する前に、対象範囲と説明を修正します。

行動面の浅さ

Skill が大まかな行動は正しく選べても、難しい下位ケースを見分けられません。分類、判断分岐、意味的な評価ファミリーを追加してください。

リソースの浅さ

参照資料は存在していても、要約しか含まれていません。実践的なガイドと、トレードオフを詳しく示した例に置き換えてください。

評価の錯覚

シナリオが酷似していたり、答えが漏れていたりするため、合格率が高くなっています。意味的な幅を広げ、オラクルを分離してください。

契約のずれ

SKILL.md、パッケージのメタデータ、エージェントのプロファイル、レジストリのエントリ、評価が、それぞれ異なる振る舞いを説明しています。リリース前に内容を一致させてください。

アンチパターン

Skill のレビューでは、次のパターンを却下してください。

• 判断や根拠を明示せず、「ベストプラクティスを使う」とだけ述べる。
• 関連性のない Skill 間で、汎用的な手順を使い回す。
• 主要な手順を言い換えただけで、画面 1 枚分にも満たない参照資料。
• 分野全体を網羅しているかのように、単純なおもちゃのような例を 1 つだけ示す。
• 1 つのシナリオに表現を変えたバリエーションを加えただけの評価スイート。
• 診断上の理由がない恣意的な再試行回数。
• 新たな根拠がなくても満たせる完了基準。
• 最も近い競合 Skill を挙げていない When NOT to Use セクション。
• すべての参照資料を重複して含み、段階的な情報開示を損なう巨大なモノリシックプロンプト。

根拠の要件

強化された Skill には、次の内容が必要です。

• 有効なパッケージ／フロントマター構造。
• 有効化と拒否の境界の明示。
• 状況の分類と判断ルール。
• 分野固有の失敗分類。
• 実質的な段階的参照資料を少なくとも 1 つ。
• ハッピーパス以外を扱う、詳しい例を少なくとも 1 つ。
• 意味的に異なる複数の評価ファミリー。
• 評価対象のコーパスが変更された際に再実行される、振る舞いに関する根拠。

引き継ぎ契約

Skill の作成を終える際は、次の内容を報告してください。

• Skill ID と担当する機能。
• 隣接する Skill と、それぞれの発動境界。
• 追加した意味的な評価ファミリー。
• 追加した段階的リソース。
• 既知の未対応ケース。
• 決定論的な検証のステータス。
• 振る舞いに関する根拠が最新か、古いか、未実行か。

完了基準

想定されるすべてのフォルダーが存在するだけで、Skill が成熟したと判断しないでください。

完了には、次の条件を満たす必要があります。

• パッケージの検証に合格している。
• 上記の契約セクションが、該当する箇所に実質的な内容として記載されている。
• リソースが重複ではなく、内容に深みを加えている。
• 評価の幅が、主要な判断と近道を検証している。
• レジストリ／ホストのメタデータに一貫性が保たれている。
• コーパスの変更によって以前の振る舞いの証明が無効になった場合、再実行するまで明示的に古いものとして扱われている。

段階的リソース

• 深さの基準：references/depth-standard-v2.md
• 既存の作成用参照資料とテンプレートは、パッケージの仕組みに関する用途で引き続き有用です。