liuchunming033/skill-doctor

Skill Doctor —— スキル健康診断ツール

フロー

1. 指定されたスキルディレクトリを読み込む
2. コアファイルが存在するか確認（SKILL.md、gotchas.md など）
3. スクリプトを呼び出し構造化レポートを取得: python scripts/analyze_skill.py <skill_path> --output json で各チェック項目のスコア、問題、提案を得る
4. 低スコア項目（<70点）ごとに、スクリプトレポートに基づき具体的な改善提案 + 予想スコア向上値 + 作業負荷評価を追加
5. 改善可能項目を全てリストアップし、ユーザーにどの項目を受け入れるか選択させる
6. ユーザーが受け入れた項目を一つずつ最適化（直接ファイルを修正）
7. 最適化完了後、再度スクリプトを呼び出し再診断し、前後比較レポートを出力する

Agent は知的層（改善提案、ユーザー対話、修正実行）を担当し、スクリプトは安定層（スコア計算、構造化出力）を担当します。スクリプトの使い方は scripts/analyze_skill.py を参照してください。

九大診断項目

検査項目	検査内容	合格基準
description 検査	機能説明ではなく、トリガー条件として書かれているか	トリガーキーワードを含み、長さ<100文字
gotchas 検査	ハマりポイントの記録があるか	gotchas.md が存在し、空でない
ファイル構成検査	3分類基準に従って構成されているか	ルートディレクトリは SKILL.md + gotchas.md + examples.md のみ、参考資料は reference/、スクリプトは scripts/、設定は config/ に配置
過剰制約検査	パスに対して過剰な制約を課していないか	「最初のステップ」「次のステップ」などの固定フローがない
既知知識検査	Agent が既に知っている内容を重複していないか	「Xとは」「Yの使い方」といったチュートリアルがない
メモリ設定検査	config.json が存在するか	config.json が存在し、適切な設定が行われている
スクリプト検査	スクリプトが必要なのに不足していないか	安定した能力が必要な場合、scripts ディレクトリが存在する
フック検査	フック設定が正しいか	PreToolUse/PostToolUse の形式が正しい
Markdown 書式検査	書式が適切か	YAML、テーブル、コードブロックの書式が正しい

診断レポート形式

{
  "skill_name": "xxx",
  "overall_score": 55,
  "grade": "D",
  "check_results": {
    "description": {"score": 50, "issues": ["機能説明として書かれている"], "suggestions": ["トリガー条件の形式に書き換える"], "expected_gain": 40},
    "gotchas": {"score": 40, "issues": ["gotchas.md が空"], "suggestions": ["3つ以上の実際のハマりポイントを追加する"], "expected_gain": 50}
  },
  "optimization_options": [
    {"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
     "effort": "低", "action": "description をトリガー条件の形式に書き換える",
     "token_saved_per_call": 50, "time_saved_per_call_sec": 0},
    {"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
     "effort": "中", "action": "実際のハマりポイントを追加する",
     "token_saved_per_call": 0, "time_saved_per_call_sec": 180}
  ],
  "overall_after_accept_all": 85,
  "total_benefits": {
    "token_saved_per_call": 200,
    "time_saved_per_call_sec": 300
  }
}

効果見積もりルール

最適化タイプ	トークン節約（1回あたり）	時間節約（1回あたり）	説明
description 短縮	余分な文字数×1トークン	—	コンテキスト読み込み量削減
gotchas 追加	—	ハマりポイントあたり2～5分	同じミスの繰り返し防止
ファイル分割	(元の行数-新しい行数)×3トークン	—	参考資料を reference/ に移動し、必要な時だけ読み込む
過剰制約→意思決定フレームワーク	固定ステップあたり×20トークン	ステップあたり10～30秒	無駄なステップ実行の削減
既知知識の削除	チュートリアル段落の長さ（トークン）	—	Agent が既知の内容を重複して記述しない
スクリプトカプセル化	—	1回あたり1～3分	Agent が毎回同じコードを書き直す手間を省く

効果は1回あたりの推定値で、実際の値はスキルの内容や使用方法によって異なります。

「時間」に関する説明: レポート中の「時間」は、設計上の欠陥によって生じる追加の無駄であり、スキル実行の総時間ではありません。具体的には:

• gotchas 欠落 → Agent が何度も同じミスでデバッグ（毎回 2～5 分）
• 過剰制約 → Agent が無意味な固定ステップを実行（毎ステップ 10～30 秒）
• スクリプト欠落 → Agent が毎回同じコードを再作成（毎回 1～3 分）

比較ロジック: 最適化前の値 = これらの無駄の合計；最適化後は無駄がゼロに → ~0；「節約」 = 排除された無駄の量。最適化後のスキル実行自体には依然として時間がかかりますが、これらの追加コストはなくなります。

改善提案の表示

レポート生成後、改善可能項目をユーザーにリスト形式で表示します。各項目に以下を含みます:

### 🔧 改善可能項目

| # | 検査項目 | 現在スコア | 予想スコア | 向上値 | 作業負荷 | トークン/回 | 時間/回 | 操作 |
|---|---------|----------|----------|------|---------|-----------|--------|------|
| 1 | description | 50 | 90 | +40 | 低 | ~50 | — | トリガー条件に書き換え |
| 2 | gotchas | 40 | 90 | +50 | 中 | — | ~3分 | 実際のハマりポイントを追加 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

**全ての改善を受け入れた場合**: 55点(D) → 85点(B)、30点向上

### 📈 総合効果（1回あたり）
- トークン節約: ~200/回
- 時間節約: ~5分/回
- エラー回避: gotchas を追加することで一般的なミスを防止

> **時間の集計基準**: ここでの「時間節約」は**設計上の欠陥による追加の無駄**であり、スキル実行の総時間ではありません:
> - gotchas 欠落 → Agent が何度も同じミスでデバッグ（毎回 2～5 分）
> - 過剰制約 → Agent が無意味な固定ステップを実行（毎ステップ 10～30 秒）
> - スクリプト欠落 → Agent が毎回同じコードを再作成（毎回 1～3 分）
> - 最適化前の値 = 無駄の合計、最適化後は無駄がゼロに、「節約」 = 排除された無駄の量

選択してください:
- **「全て受け入れる」** — 全ての項目を一括最適化
- **「1,3を受け入れる」** — 指定項目のみ最適化
- **「スキップ」** — レポートのみ確認し、最適化は行わない

ユーザー確認後の実行

1. ユーザーの選択後、対応するファイルを一つずつ修正
2. 各項目完了ごとにステータスを記録
3. 全て完了後、診断を再実行し比較レポートを生成

前後比較レポート形式

## 📊 最適化前後比較

| 検査項目 | 最適化前 | 最適化後 | 変化 |
|---------|--------|--------|------|
| description | 50 (機能説明) | 90 (トリガー条件) | +40 ⬆️ |
| gotchas | 40 (空) | 90 (充実) | +50 ⬆️ |
| ... | ... | ... | ... |
| **総スコア** | **55 (D)** | **85 (B)** | **+30 ⬆️** |

### 📈 総合効果（1回あたり）
| 次元 | 最適化前 | 最適化後 | 節約 |
|------|--------|--------|---------|
| トークン | ~800/回 | ~600/回 | ~200/回 |
| 時間の無駄 | ~5分 | ~0 | ~5分 |
| メインファイル | 466行 | 75行 | -84% |

> 時間の無駄 = 設計上の欠陥による追加コスト（デバッグ時間、冗長なステップなど）。スキル実行の総時間ではありません。[効果見積もりルール](#効果見積もりルール) を参照してください。

### 修正済みファイル
- `SKILL.md` — description を書き換え
- `gotchas.md` — 5つの実際のハマりポイントを追加

完全な対話例

examples.md の例9を参照

スコア等級

• A（90～100点）: 優秀、全てのベストプラクティスを遵守
• B（75～89点）: 良好、わずかな最適化余地あり
• C（60～74点）: 合格、明らかな改善点あり
• D（<60点）: 不合格、再構築が必要

詳細チェックリスト

checklists.md を参照

一般的なハマりポイント

gotchas.md を参照

最適化例

examples.md を参照

スクリプト

診断のコアロジックは scripts/analyze_skill.py にカプセル化されており、Agent がこれを呼び出して構造化スコアを取得します:

python scripts/analyze_skill.py <skill_path> --output json    # ステップ3：スコアレポート取得
python scripts/analyze_skill.py <skill_path> --output markdown # オプション：人間可読レポート生成

スクリプトが担当: スコア計算、問題検出、等級判定（安定層） Agent が担当: 改善提案生成、ユーザー対話、ファイル修正実行（知的層）