skill-audit は何をしますか？
SKILL.md の V3 標準（LLMフレンドリー）に対する静的監査ツール。10個のQAチェックを実行し、機械的・意味的な問題を検出、優先順位付きレポートを出力します。特に Claude pre-4.5 から移行したユーザーに有用です — 古いスキルは多くの場合、作者の環境でしか動作せず、外部エージェントでは機能しません。
使用タイミング
以下の場合に起動します：
- ユーザーのスキルが「起動しない」「正しく動作しない」
- Claude 3.x / 4.0 から 4.6+ に移行し、動作が壊れた
- スキルを GPT-5、Gemini、または Claude 以外の LLM で実行したい
- スキルを大量に作成している（例：学生、チーム、コミュニティ向け）
- コレクション内のどのスキルを優先的に修正すべきか判断したい
具体的なメッセージ例：
- "roda skill-audit em skills/my-skill/SKILL.md"
- "minha skill não dispara no GPT"
- "audita essa pasta de skills pra mim"
- "skill-audit ./skills"
- "por que essa skill funciona no Claude mas não no Gemini?"
使用すべきでないタイミング
以下の場合は起動しません：
- ユーザーがゼロからスキルを作成したい →
criar-skillまたはskill-creatorを使用 - 監査したスキルを実行したい → 直接スキルを実行
- セキュリティ監査（OWASP、本番環境のシークレット）が必要 → 別のツールを使用
- 対象ファイルが
SKILL.mdでない（例：Pythonスクリプト、README） → 汎用的なリファクタリング
入力
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| path | string | ✅ | SKILL.md のパス、または SKILL.md を含むサブフォルダがあるディレクトリ（再帰的） |
| format | string | ❌ | markdown（デフォルト）または json — レポートの形式 |
出力
| フィールド | 型 | 説明 |
|---|---|---|
| score | int 0-10 | スキルが10個のQAチェックのうちいくつ合格したか |
| issues | array | 優先順位付きの問題リスト（例：desc_no_triggers、examples_too_few） |
| by_category | object | スキルカテゴリ別の平均スコアと合格率 |
| report | markdown | ランキングとスキル別詳細を含む完全なレポート |
出力形式：./audit-results.md にマークダウンファイルとして保存 + 端末にサマリー表示。
ワークフロー
- 入力検証 — path は存在するか？
.mdファイルかディレクトリか？ - SKILL.md ファイルを収集
- path が
.mdファイルを指している場合 → 単一リスト - それ以外の場合 → ディレクトリ内で
**/SKILL.mdを再帰的に glob
- path が
- 各 SKILL.md に対して：
- YAML フロントマターをパース（
---...---） - 本体を H2 セクションに分割（コードフェンス ``` または ~~~ 内の H2 は無視）
- 10個のQAチェックを実行
- スコア + issues + カウントを記録
- YAML フロントマターをパース（
- 結果を集約 — 平均スコア、分布、最も多い issue
- マークダウンレポートを生成
./audit-results.mdに：- 全体サマリー
- スコア分布
- 頻度順の issues
- 修正が必要な上位30スキル
- スキル別詳細
- 端末にサマリーを表示 — 合計数、平均スコア、合格（≥7）数
10個のQAチェック
- 名前が kebab-case で、フォルダ名と一致するか
- Description: 50語以上、三人称、5つ以上のトリガーフレーズ、否定境界
- Workflow の各ステップが単一・命令形・曖昧でないアクションであること
- 具体的な例が2つ以上（実際の入力 → 実際の出力）
- エッジケースが3つ以上カバーされている
- 出力形式が明確に定義されている
- 曖昧な表現がゼロ（禁止語リストは
references/qa-checklist.md参照） ## When NOT to Useセクションに否定境界がある- ハードコードされた認証情報がゼロ（シークレット、APIキー、トークン）
evals/evals.jsonフォルダが存在し、2つ以上のケースがある
エッジケース
- path が存在しない場合 → exit 1、「Path não encontrado: {path}」というメッセージを表示
- ディレクトリが空（SKILL.md が0個）の場合 → exit 0、「Nenhum SKILL.md encontrado em {path}」というメッセージを表示
- SKILL.md に YAML フロントマターがない場合 → スコア 0、issue
missing_frontmatter - YAML が無効な場合 → スコア 0、issue
yaml_parse_error evals/フォルダは存在するがevals.jsonがない場合 → issueno_evals_folder- SKILL.md が非常に大きい（350行超）場合 → warning
long、内容をreferences/に移動することを推奨 - マークダウンリンク内のプレースホルダ参照（
link、url、path） → 無視（壊れた参照としてカウントしない）
例
例1 — 単一スキルの監査
実際の入力: skill-audit ./my-skill/SKILL.md
実行されたワークフロー:
./my-skill/SKILL.mdが存在することを確認- YAML をパース —
name: my-skill、description が32語であることを確認 - 本体分割:
## When to Useはあり、## When NOT to Useが欠落 - 10個のチェックを実行: description が短い（32w<50）、否定なし、evals フォルダなし、例が1つだけ
- レポート生成
実際の出力:
skill-audit: 1 skill analisada
my-skill — 6/10 (232L, 32w desc, 4 triggers, 1 ex, 4 edge, evals ✗)
Issues: desc_too_short(32w), desc_no_negatives, examples_too_few(1), no_evals_folder
Report: ./audit-results.md
例2 — フォルダ全体の監査（エッジケース：複数スキル）
実際の入力: skill-audit ~/my-claude-skills/
実行されたワークフロー:
~/my-claude-skills/がディレクトリであることを確認- Glob で 12 個の
SKILL.mdを検出 - それぞれに対して: パース + チェック + スコア付け
- 集約: 平均スコア 7.1、スコア ≥7 の合格 4/12
- 優先順位付きレポート: 悪いものから先に
実際の出力:
skill-audit: 12 skills analisadas
Score médio: 7.1/10
Passing (≥7): 4/12 (33%)
Top 3 issues mais comuns:
desc_no_negatives (12, 100%)
no_evals_folder (9, 75%)
desc_too_short (7, 58%)
Worst offenders:
1. legacy-skill-x — 3/10
2. migrated-from-gpt — 4/10
3. old-claude35-skill — 5/10
Report: ./audit-results.md
依存関係
- ランタイム: Python 3.8+
- ライブラリ: 標準ライブラリのみ（re, json, pathlib, argparse, collections）
- API: なし — 100% 静的/オフライン
- ファイル:
templates/SKILL-TEMPLATE.md+references/qa-checklist.md（読み取り専用） - 他のスキル: なし — スタンドアロンツール
エラーと復旧
| エラー | 原因 | 修正方法 |
|---|---|---|
Path não encontrado | パスが無効か、入力ミス | 絶対パスを確認; ls {path} で存在を確認 |
yaml.YAMLError | フロントマターが不正 | SKILL.md を開き、インデントと --- の閉じを確認 |
UnicodeDecodeError | SKILL.md が UTF-8 以外のエンコーディング | エディタで UTF-8 として保存 |
ModuleNotFoundError: yaml | PyYAML が不足 | pip3 install pyyaml を実行 |
| レポートが生成されない | ./audit-results.md への書き込み権限がない | 書き込み権限のあるディレクトリで実行 |
備考
スコアについて: 7/10 が、スキルを外部LLMで「トリガー信頼性あり」と見なす最低基準です。10/10 が理想的です。7未満は通常、スキルが散文で書かれ、実行可能な契約（コントラクト）になっていないことを示します — pre-V3のスキルに多い形式です。
evals.json について: チェック10は evals の内容を検証しません。ファイルの存在と、prompt と expected_output を持つ2つ以上のケースという最小限の構造のみをチェックします。evals の品質はスキル作者の責務であり、監査の対象外です。
既知の制限:
- Workflow の意味的な品質（ステップがドメインにとって妥当か）は監査しません
- スキルを実行しません（静的解析のみ）
- トリガーフレーズのヒューリスティックは、技術的に密度の高い説明文で偽陽性を出す可能性があります — スコアが境界線（6-7）の場合は手動で issue を確認してください
変更履歴
- v1.0（2026-04-19）: 初回バージョン。V3標準に基づく10個のQAチェック。 Amora ワークスペースの119スキルの監査（平均スコア5.9 → 10.0）から派生。