既存のスキルを進化させる

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つの有効なスキル参照	名前変更/削除されたスキルへの古い参照

# スキルを読む
cat skills/<skill-name>/SKILL.md

# フロントマターの解析を確認する
head -20 skills/<skill-name>/SKILL.md

# 関連スキルがまだ存在するか確認する
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の両方が必要
• 新しいピットフォールはよくある落とし穴セクションの最後に追加
• 新しい関連スキルは関連スキルセクションの最後に追加

バリアントの場合

# バリアントディレクトリを作成する
mkdir -p skills/<skill-name>-advanced/

# 元のものを出発点としてコピーする
cp skills/<skill-name>/SKILL.md skills/<skill-name>-advanced/SKILL.md

# バリアントを編集する:
# - `name` を `<skill-name>-advanced` に変更する
# - `description` を上級スコープを反映するように更新する
# - `complexity` を上げる（例: intermediate → advanced）
# - `version` を "1.0" にリセットする
# - 上級ユースケースのための手順ステップを追加/拡張する
# - 元のスキルを前提条件として関連スキルで参照する

期待結果： SKILL.md（改良または新しいバリアント）がステップ1の評価チェックリストをパスする。

失敗時： ステップの編集でドキュメント構造が壊れた場合、git diff で変更を確認し、git checkout -- <file> で部分的な編集を元に戻す。

ステップ4.5: 翻訳済みバリアントを同期する

翻訳が存在する場合に必須。 このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 古い source_commit 値は、npm run validate:translations がすべてのロケールにわたって誤った古さ警告を報告する原因となる。

進化したスキルの翻訳が存在するかどうかを確認し、新しいソース状態を反映するように更新する:

# 既存の翻訳を確認する
ls i18n/*/skills/<skill-name>/SKILL.md 2>/dev/null

翻訳が存在する場合

1. 現在のソースコミットハッシュを取得する:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. 各翻訳ファイルのフロントマターで source_commit を更新する:

for locale_file in i18n/*/skills/<skill-name>/SKILL.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. 影響を受けるロケールをコミットメッセージに含めて、再翻訳のためにファイルにフラグを立てる:

evolve(<skill-name>): <変更の説明>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <変更されたセクションをリストする>

4. 翻訳ステータスファイルを再生成する:

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: バージョンとメタデータを更新する

semver規則に従ってフロントマターの version フィールドをバンプする:

変更タイプ	バージョンバンプ	例
タイポ修正、言い回しの明確化	パッチ: 1.0 → 1.1	ステップ3の不明確な文を修正
新しいステップ、新しいピットフォール、新しいテーブル	マイナー: 1.0 → 2.0	エッジケース処理のためのステップ7を追加
手順の再構築、入力の変更	メジャー: 1.0 → 2.0	5ステップから8ステップへの再編成

また以下も更新する:

• スコープが拡大した場合の complexity（例: basic → intermediate）
• カバレッジエリアが変更された場合の tags
• スキルのスコープが実質的に異なる場合の description

期待結果： フロントマターの version が変更の大きさを反映している。新しいバリアントは "1.0" から始まる。

失敗時： バージョンをバンプするのを忘れた場合、次の進化では現在の状態と以前の状態を区別する方法がない。常にコミット前にバンプする。

ステップ6: レジストリとクロスリファレンスを更新する

改良の場合

レジストリへの変更は不要（パスは変更なし）。他のスキルで関連スキルが変更された場合のみクロスリファレンスを更新する:

# いずれかのスキルが進化したスキルを参照しているか確認する
grep -r "<skill-name>" skills/*/SKILL.md

バリアントの場合

skills/_registry.yml に新しいスキルを追加する:

- 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. スラッシュコマンド発見のためのシンリンクを作成する:

# プロジェクトレベル
ln -s ../../skills/<skill-name>-advanced .claude/skills/<skill-name>-advanced

# グローバル
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 で元のコンテンツの偶発的な削除がないことを確認

# フロントマターを確認する
head -20 skills/<skill-name>/SKILL.md

# ディスク上のスキル数 vs レジストリ
find skills -name SKILL.md | wc -l
grep total_skills skills/_registry.yml

# シンリンクを確認する（バリアントの場合）
ls -la .claude/skills/<skill-name>-advanced
readlink -f .claude/skills/<skill-name>-advanced/SKILL.md

# すべての変更を確認する
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 を使用する。環境ガイドのトラブルシューティングセクションを参照。

関連スキル

• create-skill — 新しいスキルを作成するための基盤; evolve-skillは元々これが従われたと仮定する
• commit-changes — 説明的なメッセージで進化したスキルをコミットする
• configure-git-repository — バージョン管理されたスキルの変更
• security-audit-codebase — 誤って含まれた秘密情報のために進化したスキルをレビューする