skill-health
Skill240 starsChanged 5 days agoMITView on GitHub
`.claude/skills/*/SKILL.md` の frontmatter / referenced script 実在 / trigger 衝突 / `.claude/hooks/*.sh` の executable+shebang を検査する meta-skill。 メタワークフロー監査で「hook script rot が最高リスク」と判明したため、 commit 前または skill 編集後に呼んで health check を行う。
8 other projects use a version of this.
Adopted by
Most recently taken up by
- shimo4228/akc-cycletheir own version, first seen Nov 8, 2026
- aaronjmars/miroshark-aeontheir own version, first seen Oct 21, 2026
- aeonfun/aeontheir own version, first seen Oct 20, 2026
- MiroShark/miroshark-aeontheir own version, first seen Oct 17, 2026
- shimo4228/claude-harnesstheir own version, first seen Oct 10, 2026
- shimo4228/skill-healththeir own version, first seen Oct 10, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- aaronjmars/aeon★ 794same name
- aeonfun/aeon★ 793same name
- aaronjmars/miroshark-aeon★ 20same name
- MiroShark/miroshark-aeon★ 20same name
- shimo4228/claude-harness★ 4same name
- shimo4228/akc-cycle★ 2same name
- shimo4228/skill-health★ 1same name
- TheKREATORS/my-claude-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- bump-depsSkill
- check-cross-runtimeSkill
- check-loanwordSkill
- check-new-runtime-assetSkill
- check-pr-readySkill
- check-puaSkill
- check-review-backlogSkill
- check-runtime-paritySkill
- commitSkill
- create-prSkill
- precheckSkill
- prepare-releaseSkill
- publish-modelSkill
- release-prepSkill
- reply-reviewSkill
- run-testsSkill
- sync-docsSkill
- watch-ci-patternsSkill
- watch-prSkill
The file
Files
Skill / Hook Health Check
このプロジェクトの自動化資産 (skills / tracked hook scripts / .pre-commit-config.yaml の 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 <N> skills, <M> hooks
OK skill-health: <N> skill(s), <M> hook(s) inspected2. 失敗時の対応
| エラー種別 | 修正案 |
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 に出現しても問題ないが、 「7 エージェント並列レビュー」 のような特定 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 漏れ 防止
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

