evolve-skill

# 既存のスキルを進化させる `create-skill` で元々作成されたスキルを改善、拡張、または上級バリアントを作成する。この手順はスキルライフサイクルのメンテナンス面をカバーする: ギャップの評価、的を絞った改善の適用、バージョンのバンプ、レジストリとクロスリファレンスの同期。 ## 使用タイミング - ツールの変更後にスキルの手順ステップが古くなったり不完全になった場合 - ユーザーフィードバックが欠けているピットフォール、不明確なステップ、または弱いバリデーションを明らかにした場合 - スキルをbasicからintermediate（またはintermediateからadvanced）に成長させる必要がある場合 - 元のスキルと並んで上級バリアントが必要な場合（例: `create-r-package` と `create-r-package-advanced`） - 関連するスキルが追加または削除されてクロスリファレンスが古くなった場合 ## 入力 - **必須**: 進化させる既存のSKILL.mdへのパス - **必須**: 進化のトリガー（フィードバック、ツール変更、複雑度アップグレード、新しい関連スキル、発見されたピットフォール） - **任意**: 変更する場合のターゲット複雑度レベル（basic、intermediate、advanced） - **任意**: 現場での改良ではなく上級バリアントを作成するかどうか（デフォルト: 現場での改良） ## 手順 ### ステップ1: 現在のスキルを評価する 既存のSKILL.mdを読み、品質チェックリストに対して各セクションを評価する: | セクション | 確認事項 | 一般的な問題 | |---|---|---| | フロントマター | 必須フィールドすべてが存在し、`description` が1024文字未満 | `tags` の欠落、古い `version` | | 使用タイミング | 3〜5つの具体的なトリガー条件 | 曖昧なまたは重複するトリガー | | 入力 | 必須と任意が明確に分離されている | 任意の入力のデフォルトの欠落 | | 手順 | 各ステップにコード + Expected + On failure がある | On failureブロックの欠落、実際のコマンドではなく疑似コード | | バリデーション | 各アイテムがバイナリの合否 | 主観的な基準（「コードがクリーン」） | | よくある落とし穴 | 原因と回避策を含む3〜6 | 一般的すぎる（「注意する」） | | 関連スキル | 2〜5つの有効なスキル参照 | 名前変更/削除されたスキルへの古い参照 | ```bash # Read the skill cat skills/<skill-name>/SKILL.md # Check frontmatter parses head -20 skills/<skill-name>/SKILL.md # Verify related skills still exist grep -oP '`[\w-]+`' skills/<skill-name>/SKILL.md | sort -u ``` **期待結果：** 具体的なギャップ、弱点、または改善の機会の一覧。 **失敗時：** SKILL.mdが存在しないかフロントマターがない場合、このスキルは適用されない — 代わりに `create-skill` を使用してゼロから作成する。 ### ステップ2: 進化要件を収集する 進化をトリガーしたものを特定して分類する: | トリガー | 例 | 典型的なスコープ | |---|---|---| | ユーザーフィードバック | 「ステップ3が不明確」 | 改良 | | ツール変更 | 新しいAPIバージョン、廃止されたコマンド | 改良 | | 発見されたピットフォール | 文書化されていない一般的な失敗 | 改良 | | 複雑度アップグレード | スキルが実際の使用には浅すぎる | 改良またはバリアント | | 新しい関連スキル | 隣接スキルが追加された | 改良（クロスリファレンス） | | 上級のユースケース | パワーユーザーがより深いカバレッジを必要とする | バリアント | 編集する前に必要な特定の変更を文書化する。各変更をターゲットセクションとともに一覧する。 **期待結果：** 具体的な変更のリスト（例: 「ステップ4にOn failureを追加する」「エッジケースXのための新しいステップ6を追加する」「`new-skill` を含む関連スキルを更新する」）。 **失敗時：** 変更が不明確な場合、進める前にユーザーに確認を求める。曖昧な進化目標は曖昧な改善を生む。 ### ステップ3: 進化スコープを選択する この意思決定マトリックスを使用して、現場での改良とバリアントの作成のどちらにするかを決める: | 基準 | 改良（現場での） | 上級バリアント（新しいスキル） | |---|---|---| | スキルID | 変更なし | 新しいID: `<skill>-advanced` | | ファイルパス | 同じSKILL.md | 新しいディレクトリ | | バージョンバンプ | マイナー（破壊的変更の場合のみメジャー） | 1.0から開始 | | 複雑度 | 増加する場合がある | 元よりも高い | | レジストリ | 新しいエントリなし | 新しいエントリを追加 | | シンリンク | 変更なし | 新しいシンリンクが必要 | | 元のスキル | 直接変更される | そのまま、クロスリファレンスを追加 | **改良**: 品質の向上、ギャップの修正、または適度な新しいコンテンツの追加時に選択する。スキルはそのアイデンティティを保持する。 **バリアント**: 進化したバージョンが長さを2倍にし、対象者を変更し、または実質的に異なる入力を必要とする場合に選択する。元のスキルはより単純なユースケース用にそのまま残る。 **期待結果：** 根拠を持つ明確な決定 — 改良またはバリアント。 **失敗時：** 不明確な場合、改良をデフォルトにする。後でバリアントを抽出できるが、元に戻すのは難しい。 ### ステップ4: コンテンツの変更を適用する #### 改良の場合 既存のSKILL.mdを直接編集する: - 編集のために開く - 手順ステップを追加/改訂する - Expected/On failureペアを強化する - テーブルや例を追加する - 使用タイミングのトリガーを更新する - スコープが変わった場合、入力を改訂する これらの編集ルールに従う: - 既存のすべてのセクションを保持する — コンテンツを追加し、セクションを削除しない - 挿入後のステップ番号を連続に保つ - すべての新しいまたは変更されたステップにExpectedとOn failureの両方が必要 - 新しいピットフォールはよくある落とし穴セクションの最後に追加 - 新しい関連スキルは関連スキルセクションの最後に追加 #### バリアントの場合 ```bash # Create the variant directory mkdir -p skills/<skill-name>-advanced/ # Copy the original as a starting point cp skills/<skill-name>/SKILL.md skills/<skill-name>-advanced/SKILL.md # Edit the variant: # - Change `name` to `<skill-name>-advanced` # - Update `description` to reflect the advanced scope # - Raise `complexity` (e.g., intermediate → advanced) # - Reset `version` to "1.0" # - Add/expand procedure steps for the advanced use case # - Reference the original in Related Skills as a prerequisite ``` **期待結果：** SKILL.md（改良または新しいバリアント）がステップ1の評価チェックリストをパスする。 **失敗時：** ステップの編集でドキュメント構造が壊れた場合、`git diff` で変更を確認し、`git checkout -- <file>` で部分的な編集を元に戻す。 ### ステップ4.5: 翻訳済みバリアントを同期する > **翻訳が存在する場合に必須。** このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 古い `source_commit` 値は、`npm run validate:translations` がすべてのロケールにわたって誤った古さ警告を報告する原因となる。 進化したスキルの翻訳が存在するかどうかを確認し、新しいソース状態を反映するように更新する: ```bash # Check for existing translations ls i18n/*/skills/<skill-name>/SKILL.md 2>/dev/null ``` #### 翻訳が存在する場合 1. 現在のソースコミットハッシュを取得する: ```bash npm run validate:translations ``` 2. 各翻訳ファイルのフロントマターで `source_commit` を更新する: ```bash npm run check:fence-propagation -- --id <skill-name> node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths> ``` 3. 影響を受けるロケールをコミットメッセージに含めて、再翻訳のためにファイルにフラグを立てる: ```text evolve(<skill-name>): <変更の説明> Translations flagged for re-sync: de, zh-CN, ja, es Changed sections: <変更されたセクションをリストする> ``` 4. 翻訳ステータスファイルを再生成する: ```bash npm run translation:status ``` #### 翻訳が存在しない場合 アクション不要。ステップ5に進む。 #### バリアントの場合 新しいバリアントの翻訳は、バリアントが安定するまで（1〜2バージョン）延期する。v1.2までに大幅に変わる可能性のあるv1.0バリアントを翻訳するのは労力の無駄だ。バリアントが少なくとも1回は改良された後で翻訳を追加する。 **期待結果：** すべての翻訳ファイルで `source_commit` が現在のコミットに更新されている。コミットメッセージには、どのロケールで再翻訳が必要か、どのセクションが変更されたかが記載されている。`npm run translation:status` は0で終了する。 **失敗時：** `sed` がフロントマターフィールドにマッチしない場合、翻訳ファイルが非標準のフォーマットになっている可能性がある。手動で開き、YAMLフロントマターに `source_commit` があることを確認する。フィールドが欠落している場合、ファイルは正しく足場作りされていない — `npm run translate:scaffold` で再度足場作りする。 ### ステップ5: バージョンとメタデータを更新する フロントマターの `version` フィールドをバンプする: | 変更タイプ | バージョンバンプ | 例 | |---|---|---| | タイポ修正、言い回しの明確化 | マイナー: 1.0 → 1.1 | ステップ3の不明確な文を修正 | | 新しいステップ、新しいピットフォール、新しいテーブル | マイナー: 1.0 → 1.1 | エッジケース処理のためのステップ7を追加 | | 手順の再構築、入力の変更 | メジャー: 1.0 → 2.0 | 5ステップから8ステップへの再編成 | また以下も更新する: - スコープが拡大した場合の `complexity`（例: basic → intermediate） - カバレッジエリアが変更された場合の `tags` - スキルのスコープが実質的に異なる場合の `description` **期待結果：** フロントマターの `version` が変更の大きさを反映している。新しいバリアントは `"1.0"` から始まる。 **失敗時：** バージョンをバンプするのを忘れた場合、次の進化では現在の状態と以前の状態を区別する方法がない。常にコミット前にバンプする。 ### ステップ6: レジストリとクロスリファレンスを更新する #### 改良の場合 レジストリへの変更は不要（パスは変更なし）。他のスキルで関連スキルが変更された場合のみクロスリファレンスを更新する: ```bash # Check if any skill references the evolved skill grep -r "<skill-name>" skills/*/SKILL.md ``` #### バリアントの場合 `skills/_registry.yml` に新しいスキルを追加する: ```yaml - id: <skill-name>-advanced path: <skill-name>-advanced/SKILL.md complexity: advanced language: multi description: One-line description of the advanced variant ``` 次に: 1. レジストリの先頭の `total_skills` をインクリメントする 2. 元のスキルにバリアントを指すクロスリファレンスを関連スキルに追加する 3. バリアントに元のスキルを指すクロスリファレンスを関連スキルに追加する 4. スラッシュコマンド発見のためのシンリンクを作成する: ```bash # Project-level ln -s ../../skills/<skill-name>-advanced .claude/skills/<skill-name>-advanced # Global ln -s /mnt/d/dev/p/agent-almanac/skills/<skill-name>-advanced ~/.claude/skills/<skill-name>-advanced ``` **期待結果：** レジストリの `total_skills` が `find skills -name SKILL.md | wc -l` と一致する。クロスリファレンスが双方向である。 **失敗時：** レジストリカウントが間違っている場合、`find skills -name SKILL.md | wc -l` で実際のカウントを取得し、レジストリを修正する。壊れたシンリンクについては、`readlink -f` で解決をデバッグする。 ### ステップ7: 進化したスキルを検証する 完全なバリデーションチェックリストを実行する: - [ ] SKILL.mdが期待されるパスに存在する - [ ] YAMLフロントマターがエラーなく解析される - [ ] `version` がバンプされた（改良）か "1.0" に設定された（バリアント） - [ ] すべてのセクションが存在する: 使用タイミング、入力、手順、バリデーション、よくある落とし穴、関連スキル - [ ] すべての手順ステップにExpectedとOn failureブロックがある - [ ] 関連スキルが有効で存在するスキル名を参照している - [ ] バリアントのみ: レジストリエントリが正しいパスで存在する - [ ] `total_skills` カウントがディスク上の実際のスキル数と一致する - [ ] バリアントのみ: シンリンクが正しく解決される - [ ] `git diff` で元のコンテンツの偶発的な削除がないことを確認 ```bash # Verify frontmatter head -20 skills/<skill-name>/SKILL.md # Count skills on disk vs registry find skills -name SKILL.md | wc -l grep total_skills skills/_registry.yml # Check symlinks (for variants) ls -la .claude/skills/<skill-name>-advanced readlink -f .claude/skills/<skill-name>-advanced/SKILL.md # Review all changes git diff ``` **期待結果：** すべてのチェックリストアイテムがパスする。進化したスキルはコミット準備が整っている。 **失敗時：** 各失敗したアイテムを個別に対処する。最も一般的な進化後の問題は古い `total_skills` カウントだ — 常に最後に確認する。 ## バリデーション - [ ] SKILL.mdが存在し、有効なYAMLフロントマターがある - [ ] `version` フィールドが行われた変更を反映している - [ ] すべての手順ステップにExpectedとOn failureブロックがある - [ ] 関連スキル参照が有効（壊れたクロスリファレンスなし） - [ ] レジストリの `total_skills` がディスク上の実際のカウントと一致する - [ ] バリアントの場合: `_registry.yml` に正しいパスで新しいエントリがある - [ ] バリアントの場合: `.claude/skills/` と `~/.claude/skills/` にシンリンクが作成されている - [ ] `git diff` で偶発的なコンテンツ削除がないことを確認 ## よくある落とし穴 - **バージョンのバンプを忘れる**: バージョンバンプなしでは、何が変わったか、いつ変わったかを追跡する方法がない。常にコミット前に `version` をフロントマターで更新する。 - **偶発的なコンテンツの削除**: ステップを再構築するとき、On failureブロックやテーブル行を削除しやすい。常にコミット前に `git diff` を確認する。 - **古くなったクロスリファレンス**: バリアントを作成するとき、元のスキルとバリアントの両方がお互いを参照する必要がある。一方向の参照はグラフを不完全にする。 - **レジストリカウントのずれ**: バリアントを作成した後、`total_skills` カウントをインクリメントする必要がある。これを忘れると他のスキルのバリデーション失敗を引き起こす。 - **改良中のスコープクリープ**: スキルの長さを2倍にする改良は、おそらく代わりにバリアントにすべきだ。3つ以上の新しい手順ステップを追加する場合、ステップ3のスコープ決定を再検討する。 - **NTFS マウントパスでの `git mv` を避ける（WSL）**: `/mnt/` パスでは、ディレクトリの `git mv` が壊れたパーミッション（`d?????????`）を作成する可能性がある。代わりに `mkdir -p` + ファイルのコピー + 古いパスの `git rm` を使用する。[環境ガイド](../../guides/setting-up-your-environment.md)のトラブルシューティングセクションを参照。 ## 関連スキル - `create-skill` — 新しいスキルを作成するための基盤; evolve-skillは元々これが従われたと仮定する - `commit-changes` — 説明的なメッセージで進化したスキルをコミットする - `configure-git-repository` — バージョン管理されたスキルの変更 - `security-audit-codebase` — 誤って含まれた秘密情報のために進化したスキルをレビューする