heal-skill

壊れたスキルを診断し、自動修復します。ライブラリ全体をスキャンするには `/heal-skill` を、単一のスキルを診断するには `/heal-skill ` を実行します。重大度別に問題を報告し、ヘルススコアリングを行い、ユーザーの確認を得たうえで自動修正を提案します。

<quick_start>

/heal-skill              → Full library scan (all skills)
/heal-skill <name>       → Single skill diagnosis
/heal-skill --fix        → Apply all auto-fixes (with confirmation)
/heal-skill --fix <name> → Fix single skill (with confirmation)

</quick_start>

<success_criteria>

• すべての YAML frontmatter が Anthropic の仕様に準拠して検証される
• 必要な XML セクションがすべて存在する（<objective>、<quick_start>、<success_criteria>）
• すべての config.json ファイルが正しいキーを持つ標準スキーマを使用している
• ヘルススコアを報告する：スキルごとに X/Y チェックが合格
• 自動修正はユーザーの確認を得た場合にのみ適用する（まず diff をプレビュー）
• セルフテストが合格する：/heal-skill heal-skill が問題 0 件を報告する </success_criteria>

<core_content>

3 層診断エンジン

エンジンは重大度の順にチェックを実行します。各層は前の層の上に構築されます。

Layer 1: STRUCTURAL (CRITICAL)     → Files exist, YAML parses, required fields present
Layer 2: CONTENT (HIGH)            → XML sections, line count, naming conventions
Layer 3: INTEGRATION (MEDIUM)      → config.json schema, duplicate triggers, cross-refs

レイヤー 1：構造検証（CRITICAL）

これらのチェックは、スキルがそもそも読み込めるかどうかを検証します。ここで失敗すると、スキルは壊れていることを意味します。

ID	チェック	ルール	自動修正
S1	YAML frontmatter が存在する	SKILL.md が --- で始まる	いいえ
S2	name フィールドが存在する	必須、空でない文字列	いいえ
S3	name の形式が有効	^[a-z0-9-]+$、最大 64 文字	はい — スラッグ化
S4	description フィールドが存在する	必須、空でない文字列	いいえ
S5	description の長さ	最大 1024 文字	はい — 切り詰め
S6	description に XML タグがない	値に <tags> がない	はい — タグを除去
S7	description が文字列である	YAML の配列／オブジェクトではない	はい — 配列なら結合
S7b	frontmatter のキーが有効	すべてのキーが有効なセットに含まれる（下記参照）	警告
S8	SKILL.md が存在する	スキルディレクトリに存在する必要がある	いいえ
S9	config.json が存在する	スキルディレクトリに存在する必要がある	はい — SKILL.md から生成
S10	config.json が有効な JSON である	エラーなくパースできる必要がある	いいえ

S1〜S2 の検出： 最初の 5 行を読み取り、--- 区切りと name: キーを確認します。 S3 の検出： name の値に正規表現 ^[a-z0-9-]+$ を適用し、length <= 64 を確認します。 S6 の検出： description の値に正規表現 <[a-z_]+> を適用します。 S7 の検出： YAML をパースし、型が文字列であり、配列／オブジェクトでないことを確認します。 S7b の検出： 有効な frontmatter キーは次のとおりです：name、description、disable-model-invocation、user-invocable、allowed-tools、model、context、agent、argument-hint、hooks。それ以外のキーは WARNING です（エラーではありません — 未知のキーは Claude Code によって無視され、拒否されません）。

レイヤー 2：コンテンツ品質（HIGH）

これらのチェックは、スキルが発見しやすさに関するライブラリの規約に従っているかを検証します。

ID	チェック	ルール	自動修正
C1	<objective> セクションが存在する	SKILL.md 本文に存在する必要がある	はい — スタブを追加
C2	<quick_start> セクションが存在する	SKILL.md 本文に存在する必要がある	はい — スタブを追加
C3	<success_criteria> セクションが存在する	SKILL.md 本文に存在する必要がある	はい — スタブを追加
C4	行数	本文が 500 行以下（警告のみ）	警告
C5	無効な参照リンク	内部の reference/ リンクが解決できる必要がある	はい — 無効なものを削除
C6	命名規則	ディレクトリが -skill で終わる	警告

C1〜C3 の検出： SKILL.md の本文（frontmatter より後）で <objective>、<quick_start>、<success_criteria> を検索します。 C4 の検出： wc -l SKILL.md。 C5 の検出： [text](reference/...) リンクからパスを抽出し、ファイルが存在するか確認します。 C6 の検出： ディレクトリ名が -skill で終わるか確認します。

レイヤー 3：統合の健全性（MEDIUM）

これらのチェックでは、ライブラリ全体の一貫性を検証します。

ID	チェック	ルール	自動修正
I1	config.json に標準キーがある	name、version、category が必要です	はい — 不足分を追加
I2	activation_triggers キーを使用している	triggers（旧名称）ではないこと	はい — キー名を変更
I3	depends_on キーを使用している	dependencies（旧名称）ではないこと	はい — キー名を変更
I4	version フィールドがある	version 文字列が必要です	はい — "1.0.0" を追加
I5	アクティベーショントリガーが重複していない	スキル間でトリガーが競合していないこと	警告

I2 の検出： config.json に activation_triggers ではなく triggers キーがあるか確認します。 I3 の検出： config.json に depends_on ではなく dependencies キーがあるか確認します。

---

診断フロー

1. DISCOVER
   - Scan active/ and stable/ directories
   - Build skill inventory (name, path, has SKILL.md, has config.json)

2. LAYER 1 — STRUCTURAL
   - For each skill: parse YAML frontmatter, validate fields
   - STOP on critical failures (no SKILL.md = skip remaining checks)

3. LAYER 2 — CONTENT
   - For each skill: search for XML sections, check line count
   - Check naming convention

4. LAYER 3 — INTEGRATION
   - For each skill: validate config.json schema
   - Cross-skill: check for duplicate triggers

5. REPORT
   - Generate health report grouped by severity
   - Calculate health score
   - List available auto-fixes

---

出力形式

レポートを以下の正確な形式で生成します。

SKILL HEALTH REPORT
════════════════════════════════════════════════
Scanned: X skills | Health Score: Y/Z (N%)

CRITICAL (n):
  ✗ skill-name: Description of issue [CHECK-ID]

HIGH (n):
  ⚠ skill-name: Description of issue [CHECK-ID]

MEDIUM (n):
  ℹ skill-name: Description of issue [CHECK-ID]

WARNINGS (n):
  ~ skill-name: Description of advisory [CHECK-ID]

════════════════════════════════════════════════
AUTO-FIX AVAILABLE: N issues can be auto-fixed
  Run /heal-skill --fix to preview and apply

単一スキルモード — 同じ形式ですが、対象は 1 つのスキルのみです。

重大度の定義：

• CRITICAL： スキルを読み込めない、またはアクティベートできない（S1～S10 の失敗）
• HIGH： スキルは読み込めるものの、必要なセクションが不足している（C1～C3）
• MEDIUM： ライブラリのツールに影響するスキーマの不整合（I1～I5）
• WARNING： 助言のみで、対応は不要（C4、C6）

---

自動修正プロトコル

--fix が指定された場合は、以下の正確なプロトコルに従います。

1. PREVIEW
   - Show each proposed change as a diff:
     ```
     FIX: skill-name — [CHECK-ID] Description
     --- before
     +++ after
     @@ change description @@
     -old content
     +new content
     ```

2. CONFIRM
   - Ask user: "Apply N fixes? (yes/no/select)"
   - "select" lets user pick individual fixes

3. APPLY
   - Make changes to files
   - Re-run affected checks to verify fix worked

4. RE-VALIDATE
   - Run full scan on fixed skills
   - Report new health score

チェックごとの自動修正方法：

チェック	修正方法
S3	スラグ化：小文字にし、空白や特殊文字をハイフンに置き換えます
S5	最後の文の区切りで 1024 文字に切り詰めます
S6	正規表現 </?[a-z_]+> で XML タグを空文字列に置き換えます
S7	配列の場合：要素を ". " で結合します。オブジェクトの場合：最初の値を使用します
S9	SKILL.md のフロントマターから最小限の config.json を生成します
C1	フロントマターの後に <objective>\nTODO: Add objective\n</objective> を追加します
C2	objective の後に <quick_start>\nTODO: Add quick start\n</quick_start> を追加します
C3	quick_start の後に <success_criteria>\nTODO: Add success criteria\n</success_criteria> を追加します
C5	参照先が存在しない [text](reference/...) リンクを削除します
I1	SKILL.md のフロントマターの既定値を使って、不足しているキーを追加します
I2	config.json 内の triggers を activation_triggers に変更します
I3	config.json 内の dependencies を depends_on に変更します
I4	config.json に "version": "1.0.0" を追加します

---

既知の問題パターン

これらのパターンは、実際の GitHub の issue とライブラリ監査から得られたものです。診断エンジンは、これらすべてをチェックします。

ソース	パターン	チェック
GitHub #9817	--- の前に空白があると YAML の解析に失敗する	S1
GitHub #11322	Prettier が description を複数行に整形する	S7
GitHub #17604	description 内の YAML 配列によってスラッシュコマンドがクラッシュする	S7
GitHub #6377	有効な YAML 構造であるにもかかわらず、name フィールドがない	S2
GitHub #14882	スキルがすべてのトークンを消費する（段階的な情報開示がない）	C4
GitHub #14577	/skills に「スキルが見つかりません」と表示される — フロントマターの解析に失敗	S1、S2
ライブラリ監査	8 個のスキルで XML セクションが不足している	C1～C3
ライブラリ監査	9 個のスキルが旧式の config.json キーを使用している	I2、I3
ライブラリ監査	1 個のスキルで -skill サフィックスが不足している	C6

</core_content>

<common_mistakes>

よくある問題

問題	対処方法
差分を確認せずに --fix を実行する	必ず事前にプレビューしてください。プロトコルでは確認が必要です。
警告を無視する	警告は助言ですが、技術的負債を示しています。追跡してください。
CRITICAL の問題だけを修正する	HIGH と MEDIUM の問題も、見つけやすさやツールに影響します。すべてのレイヤーを修正してください。
XML のスタブを追加したまま、内容を記入しない	スタブはプレースホルダーです。実際の内容を記述する時間を確保してください。
ライブラリ全体に問題があるのに、単一のスキルだけを修復する	まず全体をスキャンし、全体像を把握してください。

</common_mistakes>

結果サイドカーの出力

最後のステップとして、~/.claude/skill-analytics/last-outcome-heal-skill.json に書き込みます:

{"ts":"[UTC ISO8601]","skill":"heal-skill","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"skills_scanned":[n],"issues_found":[n],"fixes_applied":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに「partial」を使用します。出力がまったく生成されなかった場合にのみ「error」を使用します。

</common_mistakes>