skill-optimizer

このスキルを使うタイミング

• スキルが想定どおりに起動しない、または壊れているように見えるときに使用します
• スキルライブラリの品質を監査して改善したいときに使用します
• どのスキルが成果を出しておらず、コンテキストトークンを無駄にしているかを把握したいときに使用します

ルール

• 読み取り専用: スキルファイルは決して変更しません。レポートの出力のみを行います。
• 8 次元すべて: どれも省略しないでください。データが不十分な場合は、省略するのではなく「N/A — セッションデータが不十分」と報告します。
• 定量化: 「先週は調査タスクが 12 件あったのにスキルが一度も起動しなかった」は「調査をよく行っている」よりも優れています。
• 提案はするが、押し付けない: description の改善について具体的な文言案を提示しますが、あくまで提案として提示します。
• 根拠を示す: 起動不足の主張については、そのスキルが起動されるべきだった実際のユーザーメッセージを引用します。
• 根拠に基づく提案: description の書き換えを提案する際は、その変更を動機づける具体的な調査結果を引用します（例: 「トリガーキーワードを前方に配置する — MCP の調査では選択率が 3.6 倍改善することが示されています」）。

概要

過去のセッションデータ + 静的な品質チェックを用いてスキルを分析し、P0/P1/P2 の優先順位付き修正を含む診断レポートを出力します。各スキルを 8 次元にわたって 5 点の総合スケールで採点します。

CSO（Claude/Agent Search Optimization）= エージェントが適切なタイミングで適切なスキルを選択できるようにスキルの description を書くことです。このスキルは CSO 違反をチェックします。

使い方

• /optimize-skill → すべてのスキルをスキャンします
• /optimize-skill my-skill → 単一のスキル
• /optimize-skill skill-a skill-b → 指定した複数のスキル

データソース

現在のエージェントプラットフォームを自動検出し、対応するパスをスキャンします:

ソース	Claude Code	Codex	共有
セッショントランスクリプト	~/.claude/projects/**/*.jsonl	~/.codex/sessions/**/*.jsonl	—
スキルファイル	~/.claude/skills/*/SKILL.md	~/.codex/skills/*/SKILL.md	~/.agents/skills/*/SKILL.md

プラットフォーム検出: どのディレクトリが存在するかを確認します。利用可能なすべてのソースをスキャンします — ユーザーは Claude Code と Codex の両方をインストールしている場合があります。

ワークフロー

Identify target skills
        ↓
Collect session data (python3 scripts scan JSONL transcripts)
        ↓
Run 8 analysis dimensions
        ↓
Compute composite scores
        ↓
Output report with P0/P1/P2

ステップ 1: 対象スキルの特定

~/.claude/skills/、~/.codex/skills/、~/.agents/skills/ の順にスキルディレクトリをスキャンします。スキル名で重複を排除します（複数の場所にある同じ名前 = 同じスキル）。それぞれについて SKILL.md を読み込み、以下を抽出します:

• name、description（YAML frontmatter から）
• トリガーキーワード（description フィールドから）
• 定義されたワークフローステップ（Step 1/2/3... または Workflow 配下の ### セクション）
• 語数

ユーザーがスキル名を指定した場合は、それらのみにフィルタリングします。

ステップ 2: セッションデータの収集

Bash 経由で python3 スクリプトを使い、セッション JSONL ファイルをスキャンします。以下を抽出します:

Claude Code セッション（~/.claude/projects/**/*.jsonl）:

• Skill tool_use 呼び出し（どのスキルが呼び出されたか）
• ユーザーメッセージ（全文）
• スキル呼び出し後のアシスタントメッセージ（ワークフロー追跡用）
• スキル呼び出し後のユーザーメッセージ（反応分析用）

Codex セッション（~/.codex/sessions/**/*.jsonl）:

• session_meta イベント → スキル読み込みの証拠として base_instructions を抽出
• response_item イベント → アシスタントの出力（ワークフロー追跡）
• event_msg イベント → ツール実行とスキル関連イベント
• turn_context イベントからのユーザーメッセージ（反応分析用）

注記: Codex は明示的な Skill ツール呼び出しではなく、コンテキスト経由でスキルを注入します。スキルの読み込み（base_instructions に存在すること）は、能動的な呼び出しと等しくありません。実際の使用を検出するには、そのセッション内の response_item コンテンツでスキル固有のワークフローマーカー（ステップヘッダー、出力フォーマット）を検索します。エージェントがそのスキルに定義されたワークフローに従った出力を生成した場合にのみ、スキルは「呼び出された」と見なされます。

集計:

• スキルごと: 呼び出し回数、トリガーキーワード一致数
• スキルごと: 呼び出し後のユーザー反応のセンチメント
• スキルごと: ワークフローステップの完了マーカー

ステップ 3: 8 つの分析軸を実行する

8 つの軸すべてを必ず実行してください。 このスキルがない場合の標準的な動作では、軸 4.2、4.3、4.5b、4.8 がスキップされます。これらは最も価値の高い軸です — スキップしないでください。

4.1 トリガー率

各スキルが実際に呼び出された回数と、そのトリガーキーワードがユーザーメッセージに出現した回数をカウントします。

Claude Code: トランスクリプト内の Skill tool_use 呼び出しをカウントします。 Codex: エージェントがスキルのワークフローマーカーに従った出力を生成したセッションをカウントします（コンテキストに読み込まれただけでは不十分です）。

診断:

• 一度もトリガーされない → スキルが不要か、トリガーワードが間違っている
• キーワードの一致数 >> 実際の呼び出し数 → トリガー不足の問題。description の改善が必要
• 高頻度 → 中核スキル。最適化する価値がある

4.2 呼び出し後のユーザー反応

この軸は重要で、スキップしがちです。スキップしないでください。

セッション内でスキルが呼び出された後、ユーザーの次の 3 件のメッセージを読みます。分類:

• ネガティブ: 「違う」「間違っている」「やめて」「求めていたものではない」、ユーザーによる中断
• 修正: ユーザーが意図を再度説明し、スキルの出力を手動で上書き
• ポジティブ: 「良い」「OK」「続けて」「いいね」、ユーザーがワークフローに従う
• 無言の切り替え: ユーザーが話題を完全に変更（誤検知トリガーの可能性が高い）

スキルごとの満足率を報告します。

4.3 ワークフロー完了率

この軸は重要で、スキップしがちです。スキップしないでください。

セッションデータで見つかった各スキル呼び出しについて:

1. SKILL.md からスキルに定義されたステップを抽出する
2. そのセッションのアシスタントメッセージからステップマーカー（Step N、スキルで定義された特定の出力形式）を検索する
3. 計算する: 実行はどこまで進んだか？

報告: {skill-name} (N steps): avg completed Step X/N (Y%)

特定のステップで実行が頻繁に止まる場合は、それを指摘します。

4.4 静的品質分析

各 SKILL.md を次の 14 のルールに照らして確認します:

チェック	合格基準
Frontmatter の形式	name + description のみ、合計 < 1024 文字
name の形式	英字、数字、ハイフンのみ
description のトリガー	「Use when...」で始まる、または明示的なトリガー条件がある
description のワークフロー漏洩	description がスキルのワークフローステップを要約していない（CSO 違反）
description の積極性	description が受動的ではなく、使用すべきシナリオを積極的に主張している
Overview セクション	存在する
Rules セクション	存在する
MUST/NEVER の密度	すべて大文字の指示語をカウント。100 語あたり 5 を超える = 指摘
語数	< 500 語（超えている場合は指摘）
物語的なアンチパターン	「In session X, we found...」のようなストーリーテリングがない
YAML クォートの安全性	: を含む description は二重引用符で囲む必要がある
重要情報の位置	中核となるトリガー条件と主要なアクションが SKILL.md の最初の 20% にある必要がある
description 250 文字チェック	主要なトリガーキーワードが description の最初の 250 文字以内に出現する必要がある
トリガー条件の数	description 内のトリガー条件は 2 つ以下が理想

4.5a 誤検知率（過剰トリガー）

スキルが呼び出されたが、ユーザーがすぐに拒否または無視した場合。

4.5b トリガー不足の検出

これは最も価値の高い軸です。 各スキルについて、そのケイパビリティキーワード（単なるトリガーキーワードではなく、そのスキルができること）を抽出します。次に、ユーザーメッセージから、それらのケイパビリティに一致するタスクであるにもかかわらず、スキルが呼び出されなかったものをスキャンします。

報告: どのユーザーメッセージがスキルをトリガーすべきだったのにトリガーしなかったか、および description の改善案を提示します。

複合リスク評価: 慢性的なトリガー不足があるスキル（関連するタスクが出現した 5 セッション以上でトリガーが 0 回）については、「複合リスク」として指摘します — トリガー不足のスキルは使用フィードバックを通じて自己改善できないため、時間の経過とともにギャップが拡大します。description の即時書き直しを P0 として推奨します。

4.6 スキル間の競合

すべてのスキルのペアを比較します:

• トリガーキーワードの重複 (2 つの description に同じキーワードがある)
• ワークフローの重複 (2 つのスキルが類似したプロセスを教えている)
• ガイダンスの矛盾

4.7 環境の一貫性

各スキルについて、参照されているものを抽出します:

• ファイルパス → 存在するか確認 (test -e)
• CLI ツール → インストールされているか確認 (which)
• ディレクトリ → 存在するか確認

壊れている参照があれば報告します。

4.8 トークン経済性

この観点は重要であり、省略しがちです。省略しないでください。

各スキルについて:

• 語数 (ステップ 1 から)
• トリガー頻度 (4.1 から)
• コスト効率 = トリガー回数 / 語数
• フラグ: 大きく、一度もトリガーされていないスキルを削除または圧縮の候補として報告

段階的開示のティアチェック: 各スキルを 3 ティアの読み込みモデルに照らして評価します:

• ティア 1 (frontmatter): 約 100 トークン。確認: description は 1024 文字以下か?
• ティア 2 (SKILL.md 本文): 500 行未満を推奨。確認: 語数。
• ティア 3 (参照ファイル): オンデマンドで読み込まれる。確認: スキルは詳細な内容に参照ファイルを使っているか、それともすべてを SKILL.md に詰め込んでいるか?

参照ファイルを使わずに SKILL.md に 500 語以上を詰め込んでいるスキルは「段階的開示が不十分」として報告します。

ステップ 4: 総合スコア

各スキルを 5 段階で評価します:

スコア	意味
5	健全: 高いトリガー率、肯定的な反応、完全なワークフロー、クリーンな静的状態
4	良好: 1〜2 の観点で軽微な問題
3	要注意: 1 つの観点で重大なギャップ、または 3 つ以上で軽微なギャップ
2	問題あり: 一度もトリガーされない、または否定的なユーザー反応、または重大な静的状態の問題
1	壊れている: 動作しない、参照が欠落している、または根本的にずれている

スコア対象の観点 (加重平均):

• トリガー率: 25%
• ユーザー反応: 20%
• ワークフロー完了: 15%
• 静的品質: 15%
• アンダートリガー: 15%
• トークン経済性: 10%

定性的な観点 (報告するがスコアには含めない):

• 4.5a オーバートリガー: 件数 + 例として報告
• 4.6 スキル間の競合: 競合ペアとして報告
• 4.7 環境の一貫性: 参照ごとに合否として報告

レポート形式

# Skill Optimization Report
**Date**: {date}
**Scope**: {all / specified skills}
**Session data**: {N} sessions, {date range}

## Overview
| Skill | Triggers | Reaction | Completion | Static | Undertrigger | Token | Score |
|-------|----------|----------|------------|--------|--------------|-------|-------|
| example-skill | 2 | 100% | 86% | B+ | 1 miss | 486w | 4/5 |

## P0 Fixes (blocking usage)
1. ...

## P1 Improvements (better experience)
1. ...

## P2 Optional Optimizations
1. ...

## Per-Skill Diagnostics
### {skill-name}
#### 4.1 Trigger Rate
...
#### 4.2 User Reaction
...
(all 8 dimensions)

調査背景

このレポートの分析観点は、以下の調査に基づいています:

• アンダートリガー検出: Memento-Skills (arXiv:2603.18743) — 構造化ファイルとしてのスキルには正確なルーティングが必要であり、ルーティングされないスキルは読み書き学習ループを通じて自己改善できない
• description の品質: MCP Description Quality (arXiv:2602.18914) — 適切に書かれた description は 72% のツール選択率を達成し、ランダムベースラインの 20% に対して 3.6 倍の改善となる
• 情報の位置: Lost in the Middle (Liu et al., TACL 2024) — U 字型の LLM 注意曲線
• フォーマットの影響: He et al. (arXiv:2411.10541) — フォーマットの変更だけで 9〜40% の性能変動が生じうる
• 指示への準拠: IFEval (arXiv:2311.07911) — LLM は複数制約のあるプロンプトを苦手とする

制限事項

• このスキルは、タスクが上記で説明した範囲に明確に一致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が欠けている場合は、停止して確認を求めてください。