skill-improve - スキル品質管理・改善スキル

概要

27個のスキルの品質を体系的に管理・改善する。機械的チェックによる再現性のある評価と、LLM分析による用途適合性チェックを組み合わせ、自己改善サイクルを確立する。

2つのモード

機械的チェック 10項目

frontmatter品質チェック（追加検証）

frontmatter の description に : が含まれる場合、YAMLパーサーがエラーを起こす。" または |（リテラルブロック）で囲むこと。

3段階評価

詳細な基準・カテゴリ別重要度は references/scoring-rubric.md を参照

audit モード (/skill-improve audit)

ワークフロー

Step 1: Glob で全 SKILL.md パスを取得
        パターン: C:\Users\zooyo\.claude\skills\*\SKILL.md

Step 2: 各 SKILL.md を Read し、機械的チェック10項目を適用
        → メインエージェントが順次処理（サブエージェント不要）
        → 抽出項目: frontmatter有無、行数、コードブロック数、
          テーブル有無、各セクション有無

Step 3: 結果をテーブルで表示
        → Good / Needs Work / Critical に分類
        → 不足項目を具体的に列挙

Step 4: 改善優先度リストを提示
        → Critical > Needs Work の順
        → 各スキルに「何が足りないか」を1行で記述

出力フォーマット

## スキル品質監査結果（YYYY-MM-DD）

### Critical（要改善）
| スキル | 行数 | クリア | 不足項目 |
|--------|------|--------|---------|
| xxx | 44 | 3/10 | トリガー, コード例, テーブル, 関連スキル, 改訂履歴, トラブルシューティング, チェックリスト |

### Needs Work（改善推奨）
| スキル | 行数 | クリア | 不足項目 |
|--------|------|--------|---------|
| yyy | 180 | 6/10 | 改訂履歴, チェックリスト, トラブルシューティング, 関連スキル |

### Good（品質十分）
| スキル | 行数 | クリア |
|--------|------|--------|
| zzz | 350 | 9/10 |

### 改善優先度
1. **xxx** (Critical): トリガーワードとコード例の追加が最優先
2. **yyy** (Needs Work): 改訂履歴セクションの追加

チェックの実装手順

各 SKILL.md を Read した後、以下の順でチェック:

1. frontmatter: 1行目が "---" かつ、2行目以降に再度 "---" がある → Pass/Fail
2. name: frontmatter 内に "name:" を含む行がある → Pass/Fail
3. トリガー: ファイル全体に "トリガー:" または "トリガー：" を含む → Pass/Fail
4. 行数: 総行数が 100 <= n <= 800 → Pass/Fail
5. コードブロック: "```" の出現回数 / 2 >= 1 → Pass/Fail
6. テーブル: "|" を含む行が3行以上連続する箇所が1つ以上 → Pass/Fail
7. 関連スキル: "関連スキル" を含む見出し行(#)がある → Pass/Fail
8. 改訂履歴: "改訂履歴" or "更新履歴" を含む見出し行がある → Pass/Fail
9. トラブルシューティング: "トラブル" or "エラー" を含む見出し行がある → Pass/Fail
10. チェックリスト: "- [ ]" or "- [x]" を含む行がある → Pass/Fail
11. frontmatter品質: description に ": " を含む場合、"..." or |（リテラルブロック）で囲まれている → Pass/Fail
12. カテゴリ判定: スキル内容からワークフロー型/文書型を判定し、該当カテゴリの必須要素チェックを実施

個別改善モード (/skill-improve <skill-name>)

ワークフロー

Step 1: 対象スキルの SKILL.md を Read で読み込み
        パス: C:\Users\zooyo\.claude\skills\<skill-name>\SKILL.md

Step 2: 機械的チェック10項目を適用 → 不足項目を特定

Step 3: tasks/lessons.md から当該スキルの過去フィードバックを Grep で抽出
        パターン: "<skill-name>" を tasks/lessons.md 内で検索

Step 3.5: 教訓→スキル反映状況の棚卸し
          - tasks/lessons.md から当該スキルに関する全教訓を抽出（Step 3の結果を利用）
          - 各教訓について「SKILL.md のどのセクションに反映済みか」を照合
          - 「教訓に記述があるがスキルに未反映」のものを特定し、改善提案リストに追加

Step 4: サブエージェント（general-purpose x1）で用途適合性分析
        → references/scoring-rubric.md のプロンプトテンプレートを使用
        → スキル全文 + 過去フィードバック + 機械的チェック結果を入力
        → カテゴリ判定 + 具体的改善提案を生成

Step 5: 改善計画をユーザーに提示
        → 「構造的変更」と「軽微な整備」に分類
        → 構造的変更は承認を求める
        → 軽微な整備は自動適用可の旨を提示

Step 6: 承認後、Edit で SKILL.md を改善

Step 7: 改善後の SKILL.md を Read して検証
        → YAML frontmatter が正しく解析可能か
        → マークダウン構造が壊れていないか
        → 機械的チェックを再実行し改善を確認

Step 8: 改訂履歴セクションを更新
        → 日付 + 変更内容 + 変更理由を追記

Step 9: Codex read-only レビュー（見落とし防止）
        → 変更対象の全SKILL.mdをCodexに投げ、以下を機械的にチェック:
          - 誤字脱字（日本語・英語）
          - マークダウンテーブル構文（| の数、ヘッダー行 --- 不足）
          - パス表記の一貫性（特にスキル間クロスリファレンス）
          - 改訂履歴の日付・内容の整合性
          - YAML frontmatter の構造
        → 指摘があれば修正し、なければ完了

用途適合性分析（Step 4 詳細）

サブエージェントに以下を依頼:

• カテゴリ判定（リファレンス型/ワークフロー型/マインドセット型/プロジェクト型）
• カテゴリに応じた重要項目の評価
• 「このスキルに足りないもの」の具体的列挙
• 改善提案を「構造的変更」「軽微な整備」に分類

フィードバック記録（tasks/lessons.md に統合）

スキルに関する改善指示をユーザーから受けた場合、tasks/lessons.md に以下の形式で追記:

## YYYY-MM-DD: [スキル名] - [問題の要約]

### 問題
- [何をしようとしていたか]
- [期待動作 vs 実際の動作]

### 根本原因
- [なぜスキルが期待通りに動かなかったか]

### 対策
- [SKILL.mdに何を追加/修正したか]

### ルール
- [再発防止のルール]

CLAUDE.md の自己改善ループ（セクション3）と完全に統合。別ファイルは作成しない。

既存システムとの連携

カテゴリ別必須要素チェック

workflow skill（ワークフロー系）必須要素

ワークフロー系スキル（手順・プロセスを定義するもの）には以下の要素が含まれているかを検証する:

document skill（文書系）必須要素

文書系スキル（説明・要約・文面改善を扱うもの）には以下が含まれているかを検証する:

背景: 文書系スキルの出力品質は plain-japanese ルールと .codex/AGENTS.md の日本語品質基準に準拠すべき。監査時にこれらとの整合性を確認する。

注意事項

• audit モードではサブエージェントを使用しない（コスト・速度の最適化）
• 個別改善モードでは用途適合性分析のためサブエージェント1つのみ使用
• スキルの改善適用前に必ずユーザー承認を得る（構造的変更の場合）
• 改善後は必ず Read で検証し、YAML/マークダウン構造の破損がないことを確認

関連スキル

• codex: スキル改善案のセカンドオピニオンとして活用可能
• design-review-checklist: スキル設計時の品質チェックに応用可能
• simplify: 改善後のスキルコードレビューに活用可能

トラブルシューティング

改訂履歴