Update Skill Content

Update Skill Content

手順ステップの改善、Common Pitfallsへの実際の失敗モードの追加、Related Skillsセクションの同期、バージョン番号のバンプにより既存のSKILL.mdを向上させる。スキルがフォーマット検証を通過したが、コンテンツのギャップ、古い参照、または不完全な手順がある場合に使用する。

使用タイミング

• スキルの手順ステップが古いツール、API、またはバージョン番号を参照している場合
• Common Pitfallsセクションが薄い（3つ未満の落とし穴）または実際の失敗モードが欠けている場合
• Related Skillsセクションに壊れたクロスリファレンスがある、または関連リンクが欠けている場合
• 手順ステップに具体的なコード例がない、または曖昧な指示がある場合
• ライブラリに新しいスキルが追加され、既存スキルからクロスリファレンスすべき場合
• スキルの手順が不明確または不完全というフィードバックを受けた後

入力

• 必須: 更新するSKILL.mdファイルへのパス
• 任意: 集中するセクション（例：「procedure」、「pitfalls」、「related-skills」）
• 任意: 更新のソース（変更ログ、Issueレポート、ユーザーフィードバック）
• 任意: バージョンをバンプするかどうか（デフォルト：yes、マイナーバンプ）

手順

ステップ1: 現在のスキルを読んでコンテンツ品質を評価する

SKILL.md全体を読み、完全性と正確性について各セクションを評価する。

セクションごとの評価基準：

• When to Use: トリガーが具体的で実行可能か？（3〜5項目が期待される）
• Inputs: タイプ、デフォルト、必須/任意が明確に分離されているか？
• Procedure: 各ステップに具体的なコード、Expected、On failureがあるか？
• Validation: チェックリスト項目が客観的にテスト可能か？（5つ以上が期待される）
• Common Pitfalls: 症状と修正を含んで落とし穴が具体的か？（3〜6個が期待される）
• Related Skills: 参照されたスキルが存在するか？明らかに関連するスキルが欠けているか？

期待結果： どのセクションに改善が必要かが明確に把握でき、具体的なギャップが特定されている。

失敗時： スキルが読み込めない場合（パスエラー）はパスを確認する。SKILL.mdのYAMLフロントマターが壊れている場合は、コンテンツ更新を試みる前に review-skill-format を使用してフロントマターを修正する。

ステップ2: 古い参照の確認

変更されている可能性のあるバージョン固有の参照、ツール名、URL、APIパターンを手順ステップでスキャンする。

一般的な陳腐化の指標：

• 特定のバージョン番号（例：v1.24、R 4.3.0、Node 18）
• 移動または期限切れになっている可能性のあるURL
• 変更されたCLIフラグまたはコマンド構文
• 名称変更または非推奨になったパッケージ名
• 進化した設定ファイルフォーマット

# Check for version-specific references
grep -nE '[vV][0-9]+\.[0-9]+' skills/<skill-name>/SKILL.md

# Check for URLs
grep -nE 'https?://' skills/<skill-name>/SKILL.md

期待結果： 行番号を含む潜在的に古い参照のリスト。各参照が現在のものとして確認されるか、更新のためにフラグが立てられる。

失敗時： 手動で確認するには参照が多すぎる場合は、優先順位をつける：手順コードブロック（実行時の失敗を引き起こす可能性が最も高い）、次にCommon Pitfalls（古い回避策を参照している可能性あり）、最後に情報テキスト。

ステップ3: 正確性のために手順ステップを更新する

改善が必要と特定された各手順ステップについて：

1. コードブロックがまだ正しく実行されるか、または現在のベストプラクティスを反映しているか確認する
2. そのステップがなぜ必要かを説明するコンテキスト文を追加する
3. 具体的なコマンドが実際のパス、実際のフラグ、実際の出力を使用していることを確認する
4. 現在のツールの動作に合わせてExpectedブロックを更新する
5. 現在のエラーメッセージと修正でOn failureブロックを更新する

コードブロックを更新する際は、元の構造を保持する：

• ステップ番号の一貫性を保つ
• ### Step N: Title フォーマットを維持する
• 元の順序が誤りだった場合を除き、ステップを並び替えない

期待結果： すべての手順ステップに現在の実行可能なコードが含まれている。Expected/On failureブロックが現在の実際の動作を反映している。

失敗時： コードブロックがまだ正しいか不明な場合は、注記を追加する：<!-- TODO: Verify this command against current version -->。テストされていない代替手段で動作するコードブロックを削除しないこと。

ステップ4: Common Pitfallsを拡充する

Common Pitfallsセクションをレビューし、ギャップがある場合は拡充する。

落とし穴の品質基準：

• 各落とし穴は太字の名前で始まり、具体的な説明が続く
• 説明には症状（何が問題か）と修正方法（回避または回復する方法）が含まれる
• 落とし穴は仮説的な懸念ではなく、実際の失敗モードから導き出されている
• 3〜6個の落とし穴が目標範囲

新しい落とし穴のソース：

• 複雑なOn failureブロックを含む手順ステップ（これらは落とし穴になる可能性がある）
• 同じツールやパターンについて警告している関連スキル
• 手順のユーザーから報告された一般的な問題

期待結果： 3〜6個の落とし穴が存在し、各々に症状と修正が含まれている。「注意する」や「徹底的にテストする」のような汎用的な落とし穴がない。

失敗時： 1〜2個の落とし穴しか特定できない場合は、basicな複雑さのスキルでは許容される。intermediateおよびadvancedスキルで3つ未満の落とし穴は、著者が失敗モードを十分に探求していないことを示す — 将来の拡充のためフラグを立てる。

ステップ5: Related Skillsセクションの同期

Related Skillsセクション内のすべてのクロスリファレンスが有効であることを確認し、欠けているリンクを追加する。

1. 参照された各スキルについて、存在するか確認する：

   # Check if referenced skill exists
   test -d skills/referenced-skill-name && echo "EXISTS" || echo "NOT FOUND"
   

2. このスキルを参照しているスキルを検索する（双方向クロスリンクされるべき）：

   # Find skills that reference this skill
   grep -rl "skill-name" skills/*/SKILL.md
   

3. ドメインとタグに基づいて明らかに関連するスキルを確認する
4. フォーマットを使用する：- `skill-id` — 関係の1行説明

期待結果： 参照されたすべてのスキルがディスク上に存在する。双方向クロスリファレンスが整っている。孤立したリンクがない。

失敗時： 参照されたスキルが存在しない場合は、参照を削除するか、将来予定のスキルとしてコメント付きで記録する。このスキルを参照している多くのスキルがRelated Skillsにリストされていない場合は、最も関連性の高い2〜3個を追加する。

ステップ6: フロントマターのバージョンをバンプする

セマンティックバージョニングに従って metadata.version フィールドを更新する：

• パッチバンプ（1.0から1.1）：タイポ修正、軽微な明確化、URLの更新
• マイナーバンプ（1.0から2.0）：新しい手順ステップ、重要なコンテンツ追加、構造的変更
• 注意：スキルは簡略化された2部バージョニング（major.minor）を使用する

フロントマターに日付フィールドがある場合はそれも更新する。

期待結果： バージョンが適切にバンプされている。変更の大きさが更新の範囲と一致している。

失敗時： 現在のバージョンが解析できない場合は、"1.1" に設定し、バージョン履歴のギャップを記録するコメントを追加する。

バリデーション

• すべての手順ステップに現在の実行可能なコードまたは具体的な指示が含まれている
• 古いバージョン参照、URL、または非推奨ツール名が残っていない
• すべての手順ステップが Expected: と On failure: ブロックを持っている
• Common Pitfallsセクションに症状と修正を含む3〜6個の具体的な落とし穴がある
• すべてのRelated Skillsクロスリファレンスが既存のスキルを指している
• 密接に関連するスキルに双方向クロスリファレンスが整っている
• フロントマターのバージョンが適切にバンプされている
• 更新後も行数が500未満のままである
• SKILL.mdが変更後も review-skill-format 検証を通過する

よくある落とし穴

• テストなしでコードを更新する: 手順ステップのコマンドを動作確認なしに変更することは、古いコマンドを残すよりも悪い。不確かな場合は、テストされていない置換ではなく検証コメントを追加すること。
• 落とし穴の過度な拡充: 10以上の落とし穴を追加するとセクションが薄まる。最も影響力のある3〜6個の落とし穴を保持し、エッジケースは必要に応じて references/ ファイルに移動する。
• 更新中のクロスリファレンスの破壊: スキルを名前変更したり、ドメインを変更したりする際は、スキルライブラリ全体で古い名前への参照をgrepする。grep -rl "old-name" skills/ を使用してすべての箇所を見つける。
• バージョンをバンプし忘れる: どんなに小さなコンテンツ更新でも、バージョンをバンプする必要がある。これにより、コンシューマーがスキルが変更されたことを検出できる。
• リファクタリングへのスコープクリープ: コンテンツ更新はスキルが言っていることを改善する。セクションを再構成したり、references/ に抽出したりしている場合は、代わりに refactor-skill-structure スキルに切り替えること。

関連スキル

• review-skill-format — コンテンツ更新の前にフォーマット検証を実行して基本構造が健全であることを確認する
• refactor-skill-structure — コンテンツ更新がスキルを500行を超えた場合は、スペースを確保するために構造をリファクタリングする
• evolve-skill — コンテンツ更新を超えたより深い変更のために（例：上級バリアントの作成）
• create-skill — 新しいセクションや手順ステップを追加する際に正規フォーマット仕様を参照する
• repair-broken-references — スキルライブラリ全体にわたるバルクのクロスリファレンス修復に使用する