run-history-skill-upgrader

実行履歴スキルのアップグレーダー

言語ポリシー

ユーザー向けの出力はすべて、ユーザーの言語で記述してください。言語が不明な場合は、中国語をデフォルトとします。

役割

実際の実行フィードバックを、既存スキルの構造的な純改善につなげます。アップグレードでは、追加、変更、統合、削除、非推奨化、または変更しないという判断を行います。

ポータビリティ

このスキルはエージェントに依存しません。SKILL.md と、任意の references/、scripts/、evals/、agents/ を読み取れる Codex、Claude Code、OpenCode、OpenClaw、Hermes などのローカルエージェントホストで動作します。

• <skill-dir> は、この SKILL.md が含まれるディレクトリとして解決します。
• <python> は、ホストで利用可能な Python ランチャーを意味します。python3、python、py -3 のいずれかです。
• 固定のスキルルート、シェル、ホームディレクトリの構成、パス区切り文字を前提にしないでください。
• <skill-dir>/scripts/... のようなプレースホルダーパスは、必須の区切り文字形式ではなく、パスの各要素を表します。Windows では、シェルまたはハーネスが受け付ける区切り文字形式を使用してください。
• プラットフォーム固有のヘルパーツールは任意です。実際に利用できる場合にのみ使用してください。

必須の2段階承認

このスキルは常に plan_only から開始します。

1. plan_only：対象スキルと合意済みのエビデンス範囲を読み、具体的なアップグレード計画を提示して停止します。
2. apply_after_approval：ユーザーがその計画を明示的に承認した後にのみ、ファイルを変更します。

次の発言だけでは、承認とはみなされません。

• 「アップグレードして」；
• 「直接編集して」；
• 「確認しなくていい」；
• 「進めて」；
• スキルを改善するという最初の依頼。

有効な承認では、現在の計画を明確に示す必要があります。例：「計画 A を承認します」、「上記の計画を適用してください」、「はい、そのアップグレード計画を実行してください」。

ワークフロー

1. 対象スキルの名前とパスを確定します。
2. 現在の会話ですでに計画後の明示的な承認がある場合を除き、plan_only に固定します。
3. エビデンスの範囲を確定します。会話、ログ、スクリーンショット、成果物、差分、テスト、ソースドキュメント、ユーザーフィードバックなどが対象です。
4. 変更を提案する前に、現在の対象スキルを読みます。
5. シグナルを分類します。プロセスの不足、検証の不足、ソースの乖離、プラットフォームの乖離、ユーザーの希望、候補となるアイデア、インシデント、ルーティングの不足、コンテンツの肥大化。
6. ケースセットを設計します。インシデント、候補ルール、回帰ケース、境界ケース、任意のホールドアウトチャレンジ。
7. 一般化ゲートを通過させます。単発のインシデントが、自動的に恒久ルールに値するわけではありません。
8. ルートへの影響を割り当てます。弱いルートを削除し、機械で検証可能な事実はツール、テスト、スキーマチェック、差分、バリデーター、またはファイルに移します。
9. 純改善の形を選びます。no_change、maintenance_note_only、prune_or_consolidate、local_refactor、cross_reference_refactor、major_refactor、deprecate_or_replace_source。
10. 具体的な計画を提示して停止します。
11. 明示的な承認後にのみ適用します。
12. 検証を行い、変更内容を報告し、フォローアップが必要なリスクを記録します。

エビデンスのルール

強いエビデンス：

• ユーザーからのフィードバックまたは訂正；
• 実際の実行結果、ログ、スクリーンショット、テスト、または差分；
• 実際の対象スキルのファイル；
• ソースまたはプラットフォームの乖離を説明する公式ドキュメントまたは一次リポジトリ。

裏付けがない限り、弱いエビデンス：

• 単発のタイムアウト；
• ページの読み込み失敗が1回；
• ソースを開かずに確認した検索スニペット；
• 実行エビデンスによる裏付けのない、モデル生成のアイデア；
• 普遍的なルールであるかのように提示された、非公開パスまたは一時的なファイル名1つ。

アップグレードのルール

• 古くなったガイダンスを削除または統合することを優先し、その上に新しい注意事項を積み重ねないでください。
• 複雑な動作や重要な障害復旧を保持するために必要な場合にのみ、例を残してください。
• 一時的なユーザーの希望は、その希望が恒久的な動作として維持されることをユーザーが明確に望んでいない限り、タスク内にとどめてください。
• ホールドアウトチャレンジは適用後の検証に使い、計画の設計には使いません。
• リリースするスキルパッケージに、内部メンテナンスログを含めないでください。対象スキルにすでにそのようなログがある場合は、承認後、かつユーザーが恒久的なメンテナンス履歴をそこに残すことを望む場合にのみ更新してください。

ファイル編集の規律

変更を適用する前に、次のことを行ってください。

• 対象スキルの SKILL.md、関連する references/、scripts/、evals/、および任意のエージェントメタデータを読みます。
• 無関係なユーザー変更を保持します。
• 実用的であれば、差分またはスナップショットの参照を記録します。
• 現在承認されている計画に属するファイルのみを編集します。

認証情報、ブラウザーセッション、個人アカウントのデータ、無関係な個人用パス、または非公開のプロンプトを対象スキルに書き込まないでください。

検証

このアップグレーダースキルに同梱されているバリデーターを実行します。

<python> <skill-dir>/scripts/validate_upgrade_artifacts.py --skill <skill-dir>

この同梱バリデーターは、パッケージ構造、移植可能な Agent Skills のフロントマター項目セット、参照パス、JSON の形式、Python の構文、一般的な個人用パスの漏えい、およびアップグレーダーに必要な承認用語を確認します。依存関係を必要としないフロントマターの事前検査では、スカラー項目、ブロックテキスト、1 階層の文字列メタデータを受け入れます。それ以外の YAML 形式は推測せずに拒否します。特定のホストでは、異なる構文や、より限定された項目セットが受け入れられる場合があります。そのホストへのインストールでは、そのホストの正式なバリデーターが引き続き優先されます。どちらの構造チェックも評価ケースを実行せず、アップグレードによって動作が改善されることを証明するものではありません。

続いて、対象スキル独自のバリデーターと、関連する最小限の技術チェックを実行します。

• 変更した Python スクリプトには python -m py_compile を実行します。
• 編集した JSON ファイルには python -m json.tool を実行します。
• フロントマターの description を変更した場合は、トリガー回帰テストを実施します。
• ワークフローを変更した場合は、ルートと境界の回帰テストを実施します。
• リスクの高いアップグレードでは、元の失敗ケース、類似した肯定ケースを少なくとも 1 件、境界に近い否定ケースを少なくとも 1 件と比較します。

検証を省略した場合、または検証に失敗した場合は、アップグレードが完了したと主張しないでください。

最終回答

次の内容を報告します。

• 対象スキルとパス
• 結果が計画のみか、適用済みか
• 実際に使用したエビデンスの情報源
• 実際に変更したファイル
• 実際に実行した検証コマンドとその結果
• 削除または却下した案とその理由
• 残るリスクまたは今後の確認事項

参照資料

• references/evidence-and-scope.md
• references/upgrade-decision-protocol.md
• references/validation-and-regression.md
• references/examples.md
• scripts/validate_upgrade_artifacts.py
• evals/evals.json