optimizing-descriptions

スキルの説明を最適化する

mizchi が意図する動作でトリガーされるよう、SKILL.md の description フィールドを監査して書き直すための運用ガイドです。

上流のリファレンスは agentskills.io/skill-creation/optimizing-descriptions です。このスキルではフレームワークをそのまま維持し、その上に mizchi 固有の 2 トラックポリシーを加えています。

このガイドが必要な理由

エージェントは起動時に name + description を確認し（段階的開示）、それだけをもとに SKILL.md 全体を読み込むかどうかを判断します。description はトリガー条件のすべてです。

• 指定不足 → 起動すべき場面でスキルが起動しません。
• 範囲が広すぎる → 起動すべきでない場面でスキルが起動し、コンテキストを無駄にします。

どちらの失敗も表面化しません。つまり、スキルが単に役目を果たせていないだけです。この監査によって、それらを可視化します。

呼び出すタイミング

メタスキルです。明示的に呼び出す場合のみ使用します。トリガー：

• 「このスキルの description を最適化／監査／書き直して」
• 「agentskills に沿って description を監査して」
• 「トリガーの精度を調整して」
• 「mizchi/skills を見て description を修正して」

次の場合には使用しないでください。

• 通常のスキル作成中に行う、単一スキルの臨時編集。
• まだ使用されていない、新しく書いたスキル（superpowers:writing-skills の一環として description を作成し、誤ったトリガーが確認されてから調整してください）。

2 トラックポリシー

mizchi のスキルは 2 種類に分かれており、異なる形式の description が必要です。誤った形式を選ぶことが、監査で最もよくある見落としです。

トラック	トリガーポリシー	Description の形式	例
プロジェクト	積極的 — 自動トリガーが望ましい	Use when ... — [symptom keywords]. Trigger on [file shapes] even if user does not name [domain].	playwright-test、cloudflare-deploy、gh-fix-ci、node-sqlite-vec、aws-vault-mfa-iam
メタ	起動を抑制 — 明示的な呼び出しのみ	Invoke ONLY when the user explicitly asks ... Do NOT auto-invoke on [common ambient signals].	skill-selector、skill-finder、waxa-eval、apm-usage、empirical-prompt-tuning、retrospective-codify、chezmoi-management、このスキル

監査するスキルの分類方法：

• 本文に「Meta-skill」「explicit invocation」「明示 invoke」が含まれる → メタ。
• 本文が「X のベストプラクティス」「Y のリファレンス」「Z の使い方」である → プロジェクト。
• ペルソナ／チャット専用スキル（例：chloe-chat）は、メタ形式に従いますが、「Activate during ...」という表現を使います。

監査チェックリスト

共通（両トラック）

• 命令形の表現 — Use when ...（プロジェクト）または Invoke ONLY when ...（メタ）。後に命令形が続かない Reference for ... で始めないでください。
• ユーザーの意図に焦点を当てる — スキルの内部的な仕組みではなく、ユーザーが何をしたいかを説明します。
• 簡潔にする — 1024 文字未満（仕様上の上限です。description は最適化中に長くなりがちなため、編集のたびに確認してください）。
• 最初の節でトリガー条件を説明する — エージェントが実際に最も注目するのは name + 最初の文 です。

プロジェクトトラックの追加項目

• 症状／表層のキーワードを列挙する：ファイル名（.gleam、gleam.toml）、エラー文字列（network is unreachable、InvalidClientTokenId）、コマンド（pi.registerTool、apm install）。
• 積極的な表現を使う — even if user doesn't name <domain>／Trigger on <symptom> even when <tool> isn't mentioned。ユーザーが技術名を挙げずに問題を説明するケースを捉えます。

メタトラックの追加項目

• Invoke ONLY when ...／Use ONLY when ... で始める。
• よくある周辺シグナルを列挙した Do NOT auto-invoke on ... 節を含める（特定のファイルに触れること、特定のタスクを終えることなど、通常ならトリガーとなるシグナル）。
• ユーザーが実際に使うトリガー表現を列挙する（"codify today's lessons"、"find a Stripe skill" など）。実際の言い回しが記載されていると、エージェントは自然な表現によりよく反応します。

よくある書き換えパターン

mizchi/skills を 1 回の監査で書き換えた事例（12 件、2026-05-12）から抽出しました。

プロジェクト向けの書き換え

# Before: passive, no trigger
Reference for the dotenvx environment variable management tool.

# After: imperative + symptom + pushy
Use when working with the dotenvx env-var tool — encrypting .env, juggling
.env.production / .env.staging, committing .env.vault / .env.keys, wiring
into GitHub Actions. Trigger on `.env.vault` / `.env.keys` symptoms even
when the user does not say "dotenvx".

# Before: best-practices opener, no trigger
Best practices for building and reviewing Gleam projects on the Erlang target.

# After: imperative + file shapes + BEAM symptoms
Use when writing or reviewing Gleam on the Erlang target — Wisp + Mist HTTP
services, OTP processes, gleeunit testing. Trigger on `gleam.toml`,
`.gleam` files, or Erlang/BEAM symptoms even when "Gleam" isn't named.

# Before: describes the situation but no imperative
ECS Service Connect の DNS alias が IPv6 アドレスを返して接続できない問題の回避策。

# After: imperative + error-string symptoms
Use when ECS Service Connect の DNS alias が IPv6 アドレスを返し、 IPv4-only
の Fargate task から `network is unreachable` / `EAI_AGAIN` で接続失敗する
とき。 OTel Collector → Tempo の OTLP gRPC、 Fargate → Service Connect
の HTTP/gRPC 通信が失敗する症状から起動 (user が IPv6 と特定していなくても OK)。

Meta の書き換え

# Before: "Use after X" promotes auto-trigger
On task completion, pair "what failed first" with "what finally worked"
and codify ... Use after trial-and-error solutions to spare future-you
the same trap. Trigger phrases: "codify today's lessons," ...

# After: explicit-only with user-phrase trigger anchoring
Pair "what failed first" with "what finally worked" and codify the
should-have-known-it insight as an ast-grep rule, a skill, or a
CLAUDE.md rule. Meta-skill: invoke ONLY when the user explicitly says
"codify today's lessons," "make it a skill," "drop it into lint," or
asks to extract a reusable rule from a trial-and-error fix. Do NOT
auto-invoke at every task completion.

# Before: "Consult when touching" auto-triggers on path matches
mizchi's chezmoi dotfiles operations: source location, diff/apply flow,
skill addition, the APM vs chezmoi boundary, pre-commit. Consult when
touching ~/.claude/, ~/.config/, or ~/.zshrc, or initializing a new
machine.

# After: explicit-intent + Do NOT auto-invoke clause
Meta-skill for mizchi's chezmoi dotfiles. Invoke ONLY when the user
explicitly asks to manage / diff / apply chezmoi sources, add a skill
to dotfiles, audit the APM vs chezmoi boundary, or initialize a new
machine. Do NOT auto-invoke when the task only happens to touch a path
under ~/.claude/, ~/.config/, or ~/.zshrc — consult only on explicit
dotfile-management intent.

ワークフロー

1. 抽出 description: フィールドをすべて抽出します。簡単な手順：

   for f in */SKILL.md; do
     dir=$(dirname "$f")
     echo "=== $dir ==="
     awk 'BEGIN{in_fm=0; in_desc=0}
          /^---$/{in_fm=!in_fm; if(!in_fm) exit; next}
          in_fm && /^description:/{in_desc=1; sub(/^description:[[:space:]]*/,""); print; next}
          in_fm && in_desc && /^[a-zA-Z]+:/{in_desc=0}
          in_fm && in_desc{print}' "$f"
     echo
   done
   

2. 分類 本文に基づいて、各スキルを Meta または Project に分類します（上記の Two-track policy の表を参照）。

3. チェックリストを適用 スキルごとに適用します。不合格のチェック項目を記録し、まだ修正しないでください。

4. まとめてパッチを適用 フラグが付いた説明をすべて書き換えます。説明の調整に関するコミットとスキル本文の編集を混在させないでください。レビュー可能な説明のみの監査となるよう、差分は description: 行だけにします。

5. waxa audit <skill> で検証 表層的なフロントマターの問題（長さ、名前の形式、トリガー条件の形式）を検出します。エラーはゼロである必要があります。本文／LICENSE に関する警告はここでは対象外です。

6. ~/.claude/skills/<name>/SKILL.md に反映（mizchi の反映規約です。実行中のセッションに更新を適用するため、apm install -g --update の実行を待ちません）。

7. 1 つのコミットにまとめる メッセージにはスキルごとの要約を含めます。監査 1 回につきコミットは 1 つです。対象が 10 個以上のスキルでも同様です。

トリガー精度のテスト（次の段階）

agentskills.io のページでは、手動レビューに加えて、スキルをインストールしたエージェントにクエリセットを実行し、クエリごとのトリガー率を数え、過学習を避けるために訓練用と検証用に分割するという実証的な手順が説明されています。waxa にはまだこの機能はありません。将来のリリースで実装された際（waxa trigger サブコマンド）、このスキルによる手動監査が入力レイヤーとなり、トリガー率の測定が検証レイヤーになります。それまでは、手動監査と waxa audit を組み合わせる方法が有効です。

手作業で実証的な手順を実施する場合は、agentskills.io の詳細に従ってください。

• クエリは 20 件です。トリガーすべきクエリを約 10 件、トリガーすべきでないクエリを約 10 件にします。
• 各クエリを 3 回実行します（非決定性を平均化するため）。トリガーすべきクエリは trigger_rate ≥ 0.5、トリガーすべきでないクエリは < 0.5 で合格とします。
• 訓練用／検証用に 60／40 で分割し、訓練用ではなく検証合格率で最良の反復を選びます。
• トリガーすべきでないクエリのうち、最も価値が高いのは ニアミス です（キーワードは重複するものの、意図が異なるもの）。

よくある落とし穴

間違い	修正
トリガーに失敗したクエリの具体的なキーワードをそのまま追加する	過学習です。カテゴリに一般化します（gleam.toml exists より .gleam files）。
内部実装の観点で説明を書く	ユーザーの意図に基づいて書き換えます。「ユーザーは何をしようとしているのか？」
Meta スキルで Use after X／Consult when X と書く	周囲のシグナルで自動的にトリガーされます。Invoke ONLY when explicitly asked ... Do NOT auto-invoke on X に書き換えます。
Project スキルで ONLY when the user explicitly says ... と書く	トリガーされにくくなります。より積極的な表現にします。Use when ... Trigger on [symptoms] even if X not named.
書き換え中に説明が 1024 文字を超える	編集のたびに長さを確認します。最初に、重要度の最も低い節を削ります。
改善がないまま 5 回反復する	問題は説明ではなくクエリセットにあります。クエリ例を確認してください。簡単すぎる／難しすぎる、またはラベル付けが間違っていませんか？
同じコミットで説明と本文を書き換える	レビューも取り消しも困難になります。説明の調整は別のバッチにします。

関連項目

• agentskills.io/skill-creation/optimizing-descriptions — 上流の方法論ドキュメントです（このスキルが実践するフレームワーク）。
• superpowers:writing-skills — 新しいスキルをゼロから作成するときに使います。説明は複数ある構成要素の 1 つです。このスキル（optimizing-descriptions）は、スキルが存在し、使用状況が観察された後にのみ使います。
• waxa-eval — トリガー精度を実証的に測定します（waxa trigger の実装後）。
• waxa audit <skill> — 表層的なフロントマターの問題（長さ、名前の形式、基本的なトリガー条件の表現）を検出します。この監査で指摘される問題とも重複するため、簡易的な事前チェックに便利です。
• skill-finder — その評価基準には、このスキルの共通チェックリストと重複する「frontmatter-health」が含まれています。skill-finder は、外部スキル候補を評価する際に optimizing-descriptions のパターンを暗黙的に使用します。