writing-skills

スキルの作成

目的

無関係な作業を制約せず、判断を変える、またはタスクの実行を改善する、最小限の再利用可能なスキルを作成します。スキルの変更は、コードの TDD ではなく、動作の検証を通じて行います。この検証で aegis:test-driven-development を読み込む必要はありません。

デフォルトの進め方

1. 必要性と所有者を明確にする

• 再利用可能な動作上の不足、対象となるユーザー／ホスト、対象外の事項を明確にします。
• 既存のスキル、プロジェクトルール、ホストアダプター、自動チェックがすでに対応していないか確認します。既存の中で最小の所有者を優先してください。
• 既存のスキルについては、変更または廃止する前に、参照資料、マニフェストや生成済みコピー、検出テスト、同梱リソースを確認します。
• 再利用可能で、自明ではないガイダンスに限ってスキルを作成します。一度限りのプロジェクト規約はプロジェクト側の所有者に置き、機械的な制約は実用的な場合に自動化します。

2. 編集前に動作を記録する

指示をただ言い直すよう求める質問ではなく、代表的なタスクを使います。

• 新しいスキルの場合：スキルなしの対照テストを実行します。
• 既存のスキルの場合：まず現行版を実行します。スキル自体が必要かを検証する場合に限り、スキルなしのアブレーションテストを追加します。
• 肯定的な適用ケース、紛らわしい不適用ケース、スキルの種類に応じた負荷または適用ケースを網羅します。
• 判断、呼び出し漏れや余分な呼び出し、安全でない回避策、根拠の参照先、不明点を記録します。行数やバイト数を動作の証拠として扱ってはいけません。

有意義な動作を評価できない場合は、needs-verification の段階で止めます。スキルがデプロイ可能、または能力を維持していると主張してはいけません。

3. 指示の最小限の範囲を設計する

• エージェントには能力があることを前提とします。自明ではないコンテキスト、判断基準、安全上の境界、または省略によって観察された不足が生じた手順だけを含めます。
• 具体性の度合いはリスクに合わせます。自由度の高い作業では判断の余地を残し、壊れやすい操作、権限に関わる操作、または安全上重要な操作に限って厳密な手順を示します。
• 説明は簡潔な三人称で、対象を明確に区別できるものにします。能力と適用条件を示し、誤った振り分けを防ぐ場合に限って除外条件を追加します。説明を手続き上の近道にしてはいけません。
• 実行可能なデフォルトの進め方と省略不可の制約は SKILL.md に記載します。条件付きの詳細が多い場合は直接参照する資料に移し、それを読むべき根拠となる条件を示します。
• 実用上可能な限り、参照は1階層にとどめます。すべての参照資料をデフォルトで読み込んだり、その内容を本文に重複して記載したりしてはいけません。
• 判断や出力を実質的に安定させる場合に限り、例を追加します。通常は代表的な例を1つ示せば十分です。
• 移植可能な手法の指示は、ホストに依存しない内容にします。ホスト固有のツール名、インストール先、UI の操作手順は、そのホストが管理するドキュメントに記載します。

標準的なリポジトリ構成は skills/<skill-name>/SKILL.md と、ワークフローで実際に使う補足参照資料、スクリプト、アセットのみです。任意のメタデータについては、ベンダーのマニュアルをスキルにコピーするのではなく、リポジトリのホスト向けドキュメント、または対象ホストの最新の仕様を使用します。

4. 変更を最小限にする

観察された不足に対処し、置き換えられた重複は同じ変更単位で取り除きます。公開されている帰属表示と、外部から支えられている契約は維持します。内部の所有者、フォールバック、またはリソースを廃止する場合は、aegis:anti-entropy-governance を組み合わせます。依存関係の根拠がないまま、互換性のためのコピーを残してはいけません。

1つのモデル特有の言い回し、過去の1件のインシデント、または仮定上のエッジケースを、普遍的なルールにしてはいけません。

5. 候補を検証する

同等のモデル、ツール、ホスト構成の下で、同じポジティブ、ネガティブ、およびプレッシャー/アプリケーションのシナリオを再実行します。文言ではなく結果を比較します。

また、以下も検証します：

• frontmatter、name、description がサポート対象のホストでパースされること；
• 意図されたリクエストでは引き続きスキルが検出され、近接する誤検出では検出されないこと；
• すべての条件付き参照が明示的なトリガーから到達可能であること；
• 変更されたスクリプトが正常に実行されること；
• 廃止されたファイルと指示に有効な参照が残っていないこと；
• 変更された範囲に関連するリポジトリのワークフロー、境界、パッケージング、およびホストのチェックが合格すること。

動作がリグレッションした場合は、欠落している責務を復元するか、変更を絞り込みます。それを覆い隠すために第二のオーナーやフォールバックを追加しないでください。

シナリオの選定

スキルの種類	代表的なエビデンス
規律または安全性	現実的なプレッシャーと認可の境界
テクニック	適用、バリエーション、および情報不足のケース
パターン	認識、適用、および反例のケース
リファレンス	検索、正しい使用、およびよくあるギャップのケース

独立した評価者が信頼性を高める複雑または高リスクのスキルについては、testing-skills-with-subagents.md をお読みください。

完了記録

結果は、自然な文章または同等のフィールドで、簡潔かつ監査可能な形に保ちます：

• 動作のギャップと正規のオーナー；
• ベースラインと候補のシナリオ結果；
• 保持された責務/リソースと廃止された責務/リソース；
• トリガーと参照のチェック；
• 検証コマンドと未カバーのホスト/モデル；
• ステータス：verified、needs-verification、または blocked。

これはメソッドパックのエビデンスであり、権威ある完了またはデプロイの承認ではありません。