| name | skill-health |
| description | `.claude/skills/*/SKILL.md` の frontmatter / referenced script 実在 / trigger 衝突 / `.claude/hooks/*.sh` の executable+shebang を検査する meta-skill。 メタワークフロー監査で「hook script rot が最高リスク」と判明したため、 commit 前または skill 編集後に呼んで health check を行う。 |
Skill / Hook Health Check
このプロジェクトの自動化資産 (16 skill + 5 hook + 49 pre-commit hook) を meta-level で健全性検証する。
memory feedback_conservative_changes.md に従い、 read-only、 検査結果を report として返すのみ。 修正は別 skill / 手動で。
カバー範囲
| 検証対象 | 内容 |
|---|
| SKILL.md frontmatter | name / description / allowed-tools の必須 key、 description 長 |
| name ↔ directory 一致 | .claude/skills/foo/SKILL.md の name: foo であること |
| scripts/*.py 参照 | SKILL.md 内で参照されるスクリプトが repo 内に実在 |
| trigger 衝突 | 複数 skill の description で同じ 「...」 が使われていないか |
| hook 実行可能性 | .claude/hooks/*.sh の executable bit + shebang |
実行ステップ
1. 検査スクリプト実行
uv run python scripts/check_skill_health.py --verbose
期待出力例:
inspected 16 skills, 5 hooks
OK skill-health: 16 skill(s), 5 hook(s) inspected
2. 失敗時の対応
| エラー種別 | 修正案 |
|---|
frontmatter not parseable | YAML 構文エラー。 --- 行 + key: value を見直す |
missing frontmatter key: name | SKILL.md 冒頭に name 追加 |
name does not match directory | ディレクトリ名と SKILL.md の name を揃える |
references <path> but file does not exist | 参照されるスクリプトを作るか SKILL.md から消す |
trigger fragment used by: [...] | 複数 skill で同じ trigger 文言 → どちらかを書き換えて曖昧性除去 |
not executable | chmod +x .claude/hooks/*.sh |
no shebang on line 1 | #!/usr/bin/env bash を 1 行目に追加 |
3. CI 連携
このチェック自体は CI gate にする選択もあるが、 false positive (trigger 衝突警告は意図的なケースもある) のため pre-commit には入れずに skill 経由で呼ぶ。
将来、 false positive を減らせた段階で pre-commit hook 化を検討。
注意
- memory feedback_conservative_changes: 自動修復しない。 検査結果のみ。
- trigger 衝突: 「コミット前」 のような短い fragment は多数 skill に出現しても問題ないが、 「6 エージェント並列レビュー」 のような特定 skill 専用文言が他に漏れていたら衝突。
- frontmatter 長さ警告: description は 80-400 chars が推奨。 800 chars 超は単一文を超えており指針違反。
使用例
# 全 skill / hook の health check
/skill-health
# verbose で全 skill / hook を一覧
/skill-health verbose
期待効果
- skill / hook の script reference rot を pre-commit 入れなくても定期検査可
name ↔ directory ミスマッチ (skill 追加時の rename 忘れ) の早期発見- trigger 衝突 の検出 (どの skill が呼ばれるべきか LLM に曖昧)
.claude/hooks/*.sh の shebang 漏れ / executable 漏れ 防止
