skill-health

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 漏れ 防止