reflect

振り返り

現在のセッションを分析し、得られた知見をスキルの作成元ソースパッケージへの具体的な編集に反映します。スキルとはフォルダー全体を指し、SKILL.md だけではありません。

ワークフロー

1. スキルを特定する

会話をスキャンして、次の項目から使用されたスキルを自動検出します。

• <command-name>/skill-name</command-name> タグ
• スキルディレクトリにあるスキルのソースファイル（SKILL.md または <skill-name>.md）の読み込み

引数としてスキル名が指定されている場合は、その名前を直接使用します。

複数のスキルが検出された場合は、どれを分析するかユーザーに確認します。何も検出されず、引数も指定されていない場合は、利用可能なスキルを一覧表示して確認します。

インストール済みスキルのソースリポジトリは、グローバルインストールの場合は ~/.agents/.skill-lock.json、プロジェクトへのインストールの場合は <project-root>/skills-lock.json に記録されています。対応するローカルチェックアウトからスキルのソースパッケージを特定してください（スキルによってリポジトリが異なる場合があります）。

変更を決める前に、作成元ソースのパッケージを確認します。SKILL.md、scripts/、スクリプトのテスト、references/、templates/、assets/、フック、マニフェスト、パッケージ固有の検証手順を確認してください。最初に git のステータスを確認します。既存の未コミット変更は、別の人の作業であるものとして扱い、そうではないと確認できない限り、上書きしたり、知らないうちに取り込んだりしないでください。

読み取り専用コマンドを使って、選択したチェックアウトの git ルート、リモート URL、現在のブランチを確認します。変更案の概要にこの3点をすべて記載し、編集前に、その公開先が間違いないことをユーザーに確認します。古い source: パス、予期しないリモート、detached HEAD、または確認の欠如がある場合は、適用フェーズを中止します。スキル名から意図されたリポジトリを推測してはいけません。

2. 会話を分析する

次のシグナルについて会話をスキャンします。

シグナル	確度	確認する内容
訂正	高	ユーザーが「違います」「そうではありません」「つまり……」と言った、出力を明示的に訂正した、生成直後に変更を依頼した
成功	中	ユーザーが「完璧です」「すばらしい」「そのとおり」と言った、修正なしで受け入れた、出力を基に作業を続けた
エッジケース	中	スキルが想定していなかった質問、回避策が必要だった状況、カバーされていない機能
好み	低	ユーザーの選択に繰り返し見られる傾向、暗黙のスタイルやツールの好み
トリガーの誤作動	高	スキルが起動すべきだったのに起動しなかった、または別のスキルが起動した（本文ではなく description／トリガーの問題）

スキルの変更事項として取り込まないもの：一度限り、または特定の状況に限った指示（「今回はこれだけ」「このリポジトリだけ」など）、質問、具体的な理由のない漠然とした称賛、今後の実行に一般化できない内容。長期的に役立つシグナルだけを反映します。

シグナルは、該当する動作を担うリソースに割り当てます。

• 実行時または変換処理の不具合：同梱スクリプトまたはフックを調査して変更し、回帰テストを追加します。実行可能な動作の問題をプロンプト文面でごまかしてはいけません。
• 使用方法、順序、安全性、トリガーの不具合：SKILL.md またはその description を変更します。
• 詳細な事実情報のガイダンス：担当するリファレンスを変更します。ルーティングまたは公開仕様が変わる場合に限り、SKILL.md も更新します。
• テンプレート／アセットの不具合：ソースのテンプレート／アセットと、それを対象とする検証を変更します。
• CLI または出力仕様の変更：実装、テスト、SKILL.md、関連するリファレンスをすべて更新します。

関連する同梱リソースだけを読みますが、選択した動作を理解し検証するのに必要なファイルはすべて確認してください。

3. 変更を提案する

変更対象は、作成済みのパッケージリソースであればどれでもかまいません。根拠が示す範囲で、関連性のある最小限の変更セットを選んでください。回帰テストを伴わないスクリプトの修正は不完全です。ユーザー向けコマンドを変更する場合、そのスキルやリファレンスの更新も必要です。

実行可能なシグナルが見つからない場合は、スキルの動作が良好だったことを報告し、次の文で締めくくってください。

[skill-name] に改善点はありませんでした。このセッションではスキルは良好に動作しました。

それ以外の場合は、調査結果を提示してください。

+-- Skill Reflection: [skill-name] ----------------------------+
|                                                               |
|  Signals: X corrections, Y successes, Z edge cases           |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Files: "specific change description"                |
|  [MED]  + Files: "specific change description"                |
|  [LOW]  ~ Note: "observation for review"                      |
|                                                               |
|  Target: "<git root> | <remote> | <branch>"                   |
|                                                               |
|  Validation: "tests/lint/commands to run"                     |
|                                                               |
|  Commit: "[skill]: [summary of changes]"                      |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

4. 適用する（承認された場合）

1. 作成済みのソースパッケージを特定し、その git ルート、リモート、ブランチを表示して確認を得てから、git のステータスを再確認します。対象が確認されていない場合や、既存の変更と重複する場合は、作業を止めて確認を求めてください。
2. SKILL.md を読み、パッケージの内容を一覧化し、関連する実装、リソース、テストをすべて読みます。
3. 承認された変更を、該当するすべてのソースファイルに適用します。無関係な作業は保持してください。
4. パッケージの対象を絞ったテストと、文書化されているスキルの lint／検証を実行します。スクリプトの動作を変更する場合、変更前の動作では失敗し、修正後には成功する回帰テストが必要です。
5. パッケージの最終差分を確認します。コミット／プッシュの直前に git ルート、リモート、ブランチを再取得して表示し、同じ対象であることをユーザーに再確認します。値が変わっている場合、または確認が得られない場合は作業を止めてください。確認済みのソースリポジトリに、対象ファイルのみをコミットしてプッシュします。
6. 次のように確認します。「スキルパッケージを更新し、テストを実行して、プッシュしました。」

承認されなかった場合は、その旨を伝えて終了してください。

5. 整理する（スキルが肥大化している場合）

振り返りでは、追加するだけでなく整理も行います。パッケージが長くなっている場合や、重複するガイダンス／リソースが蓄積している場合（SKILL.md であれば、目安として100行を超える場合）は、整理を行ってください。

• 重複またはほぼ重複する項目を統合します。
• 古くなったガイダンスや、新しい項目に置き換えられたガイダンスを削除します。
• 関連する項目を適切なセクションにまとめ直します。
• 参照元と削除方法が確認できた場合に限り、使われなくなったスクリプト、リファレンス、テンプレート、テスト、アセットを削除または統合します。

同じ提案／承認の手順（手順3～4）で提示してください。全体の分量を減らすことは望ましい結果です。

例

ユーザーが、グラデーションの使い方と暗い背景色を修正したフロントエンドデザインのセッション後に /reflect を実行します。

+-- Skill Reflection: frontend-design -------------------------+
|                                                               |
|  Signals: 2 corrections, 3 successes                         |
|                                                               |
|  Proposed changes:                                            |
|                                                               |
|  [HIGH] + Constraints: "Never use gradients unless            |
|           explicitly requested"                               |
|  [HIGH] + Color & Theme: "Dark backgrounds: use #000,         |
|           not #1a1a1a"                                        |
|  [MED]  + Layout: "Prefer CSS Grid for card layouts"          |
|                                                               |
|  Commit: "frontend-design: no gradients, #000 dark bg"        |
|                                                               |
+---------------------------------------------------------------+

Apply these changes? [Y/n] or describe tweaks

制約

• 適用前に、提案する変更内容を必ず正確に提示してください。
• ユーザーの明示的な承認なしに、スキルパッケージを変更してはいけません。
• プッシュするのは、コミットが成功した後に限ります。
• エージェントのスキルディレクトリにある生成済み／インストール済みのコピーではなく、リポジトリ内の作成済みソースパッケージを編集してください（更新時に上書きされるためです）。
• スクリプト、フック、パーサー、変換、出力契約を変更する場合は、回帰テストを追加または更新してください。
• 実行可能な動作や CLI の使い方を変更する場合は、手順／リファレンスを更新してください。
• 並行するガイダンスを追加するのではなく、既存のリソースの編集や統合を優先し、パッケージを簡潔に保ってください。