agentleFS
ayutazayutaz/piper-plus/.claude/skills/skill-health/SKILL.md

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

The file

Files
SKILL.md

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 frontmattername / 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) inspected

2. 失敗時の対応

エラー種別修正案
frontmatter not parseableYAML 構文エラー。 --- 行 + key: value を見直す
missing frontmatter key: nameSKILL.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 executablechmod +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 漏れ 防止

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.