triggering-reliability

トリガーされなくなるよくあるミス

このスキルは、Claude Code のエージェントやスキルがトリガーされなくなる原因をすべてまとめたリファレンスカタログです。以下のミスはすべて、実際のプラグインで確認されています。プラグインをリリースする前のチェックリストとして、また、既存のプラグインを問題なくインストールできたのに何も起きない場合に、最初に確認する場所として活用してください。

クイックトリアージ：症状から原因を特定

症状	最も考えられる原因
スキルのディレクトリはあるが、読み込まれない	YAML フロントマターがない（ファイルが --- ではなく # で始まっている）
エージェントファイルはあるが、名前で呼び出せない	name: フィールドがないのに、非推奨の agent: true フラグが使われている
明らかに該当するクエリでも、エージェントがほとんどトリガーされない	<example> ブロックがない、または抽象的な能力を説明する記述になっている
スキルが一貫してトリガーされない	説明が、いつ使うかではなく、何をするかを記述している
複数のスキルが同じクエリを取り合う	説明内のトリガーフレーズが重複している
エージェントの説明が、汎用的で無関係なクエリにも一致する	YAML の description: 内にある Windows／ドキュメント向けの定型文がルーティングを妨げている
エージェントが誤ったモデルを使う	model: フィールドがない、または inherit ではなく値がハードコードされている

代表的なアンチパターン 9 件（概要）

それぞれの症状／根本原因／修正方法の詳しい説明は、references/anti-patterns-catalog.md を参照してください。簡易表は以下のとおりです。

#	アンチパターン	深刻度	一行での修正方法
1	フロントマターがないスキル — --- がない	P0	標準の YAML フロントマター（name:、description:）を追加する
2	非推奨の agent: true フラグ	P0	name: <kebab> に置き換える
3	抽象的な「Use this agent for X」という説明	P1	PROACTIVELY activate for: (1)... (N)... と Provides: を含むように書き直す
4	説明が、いつ使うかではなく、何をするかを記述している	P1	ユーザーの意図に基づくトリガーに切り替え、PROACTIVELY activate for: で始める
5	<example> ブロックがない、肥大化した（2,500 語超の）エージェント	P1	例外となる簡潔なオーケストレーターを除き、3～5 個の例ブロックを追加する
6	YAML の description: 内に Windows／ドキュメント向けの定型文がある	P0	定型文を名前付きの本文セクションに移動する
7	model: フィールドがない、または値がハードコードされている	P2	model: inherit に設定する
8	スキル間でトリガーフレーズが重複している	P1	担当範囲を明確に分け、スキルのアクティベーション表に区別方法を追加する
9	説明が 1024 文字を超えている、または薄いトリガーが 15 個以上ある	P1	400～1000 文字に短縮し、トリガーを冒頭に配置する。必要に応じてスキルを分割する

「例のない簡潔なオーケストレーター」はアンチパターン 5 には該当しません。監査中に例を再追加する前に、agent-development の階層表と agent-development/references/validation-and-audits.md の監査に関する注意事項を確認してください。

説明の長さの上限（アンチパターン 9 より）

• 400～1000 文字 — 推奨範囲です。
• 1024 文字 — Claude Code API 仕様の厳格な上限です。絶対に超えないでください。
• 1536 文字 — 現在の一覧表示の上限です（説明と when_to_use の合計、v2.1.105 以降）。
• コンテキストウィンドウの約 1% — インストール済みの全スキルで共有する合計予算です。

トリガーは説明の冒頭に配置してください。説明が切り詰められた場合でも、冒頭部分は残ります。

既存プラグインの監査プロセス

リポジトリのルートから、優先順位の順（P0 → P2）に監査スイープを実行します。出力の各行はトリガーに関する不具合です。影響範囲の大きいものから先に修正してください。

Bash と PowerShell の完全なスイープスクリプト（7 つの監査プローブと、肯定的なシグナルを検証する grep）は、references/audit-greps.md にあります。簡易版のワンライナーは、このファイルの末尾にある One-line greps for the canonical checks にも再掲されています。

ミスごとの修正優先度

1. P0 - フロントマターがないスキルと agent: true のエージェント（認識されない／動作しない）。
2. P0 - YAML 内の Windows／ドキュメント用の定型文（ルーティングを実際に阻害します）。
3. P1 - 複数のスキルを支える大規模エージェント（本文が2,500語超）に <example> ブロックがない。2,500語未満の簡潔なオーケストレーターは、設計上、対象外です。
4. P1 - 説明に PROACTIVELY activate for:／Provides: の列挙がない。
5. P2 - メタデータの整理（model: inherit、color:、tools: の厳密化）。
6. P2 - トリガーフレーズの重複監査と明確化。

優先度順に修正してください。P0 の不具合がある間は、P2 に時間を費やさないでください。

重要度レベルと説明の長さの上限

指摘を報告する際は、P0／P1／P2 のレベル（プラグインの動作を妨げる／ルーティングの信頼性が低い／仕上げ）を使用してください。説明の長さには3つの上限があります。API 仕様のハード上限は1,024文字、Claude がルーティング時に参照する一覧表示の上限は1,536文字、インストール済みの全スキルを合わせたコンテキストウィンドウの予算は約1%です。

各重要度の具体例を含む完全なレベル表、値と意味を示す説明の長さの上限表、作成時の目標については、references/severity-and-limits.md を参照してください。

コミット前のサイズおよびDRYゲート（必須）

SKILL.md または参照ファイルに内容を追加する前に、2つのゲートを実行します。

1. サイズゲート — 対象ファイルに対して wc -w（または PowerShell の Measure-Object -Word）を実行します。2,800～3,000語の範囲にある場合は、追加する前に、参照用のセクションを references/ に切り出します。3,000語を超えている場合は、すでに問題があるため、ほかの作業に着手する前に2,000語未満まで切り出してください。
2. DRYゲート — 候補ブロックの最初の特徴的な行について、skills/、agents/、commands/、README.md 全体を grep -rn（または Select-String）で検索します。ほかの場所に1件でも一致があれば、そのブロックを貼り付けるのではなく、skills/_shared/（複数スキル間で共有）または references/（単一スキル用）に切り出す必要があります。

完全な判定表、bash および PowerShell 用の正確なコマンド、統合ワークフローについては、references/size-and-dry-gates.md を参照してください。

公開前の標準チェックリスト

26項目からなる完全なチェックリスト（plugin.json の形式、エージェントとスキルのフロントマター、説明の内容、DRYゲートの grep、コードサンプルの妥当性、サイズ上限、NOTICES.md、marketplace.json への登録）は、references/pre-publish-checklist.md にあります。リリース前にすべての項目を実行してください。

コードサンプルの健全性チェック

コードフェンス内には、読み手に気づかれないまま問題を引き起こす欠陥がよく紛れ込みます。

1. スマート句読点（曲がった引用符、em/en ダッシュ、Unicode の省略記号）がコードフェンス内にあると、コピー＆ペーストが壊れます。grep で一致しなくなり、JSON の解析に失敗し、シェルの引用符が正しく機能しなくなります。自動修正を有効にしたエディターで入力したり、ワープロから貼り付けたりすると、作者が気づかないうちに混入します。
2. コードフェンスに言語タグがないと（```bash／```powershell／```yaml ではなく、``` だけで始めると）、構文ハイライトが無効になり、さらに悪いことに、想定しているプラットフォームが分からなくなります。bash 専用のスニペットがプレーンテキストとして表示されると、PowerShell のスニペットと見分けがつきません。Windows の読者がコピーして実行し、理由が分からないまま失敗することになります。

コードサンプルの健全性チェックリスト — リリース前に毎回実施してください。 未チェックの項目はすべて、手動で修正すべき指摘事項です。

• コードフェンス内にスマート句読点のコードポイント（U+2026、U+201C/D、U+2018/9、U+2013/4）が含まれていないこと。ASCII の同等文字である ...、"、'、- に置き換えてください。
• すべてのコードフェンスが言語タグ付きで始まること（例：```bash, ```powershell, ```yaml, ```json, ```python, ```markdown）。``` だけで始めるのは欠陥です。
• 実行可能なスニペットはすべて、両形式（POSIX と PowerShell の両方を示す）にするか、フェンスの直前に On bash/macOS/Linux: または On PowerShell (Windows): のような1行の説明を置いて対象プラットフォームを明示し、フェンスの言語タグもそれに合わせてください。

このリポジトリの主要なシェルは Windows 上の PowerShell なので、プラットフォームタグのない bash 専用スニペットは欠陥です。

網羅的なチェックと文字一覧： references/code-sample-sanity.md にある bash と PowerShell のチェック用スクリプト（スマート句読点の検出とフェンスの言語タグの検出）、スマート引用符から ASCII 文字への修正表、認識される言語タグの一覧を参照してください。

正規の品質ゲートとしてのバリデーター

このマーケットプレイスで「実際に問題となる欠陥」と見なすものの唯一の基準は scripts/validate_plugins.py です。以下の手動 grep は指摘事項を見つけるのに役立ちますが、リリース可否を決めるのはバリデーターです。

python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build

このスキルに関係するバリデーターの主なルール：

バリデーターチェック	重大度	対応先
Skill missing frontmatter	エラー	アンチパターン 1
Deprecated agent: true	エラー	アンチパターン 2
Skill missing PROACTIVELY / Provides	警告	アンチパターン 3～4
Agent missing PROACTIVELY / Provides	警告	アンチパターン 3～4
Agent missing examples	警告	アンチパターン 5 — エージェントの本文が2,500語を超える場合のみ発生
Agent missing model: inherit	エラー	アンチパターン 7
Description / SKILL.md の長さチェック	エラー／警告	アンチパターン 9 ＋ サイズ上限

エージェント、スキル、プラグインの各レベルにおけるバリデータールールの完全な一覧と、既知のバリデーターの不足点は agent-development/references/validation-and-audits.md にあります。その表とバリデーターのコードが常に一致するようにしてください。

監査上の注意：修正を推奨する前に意図を確認する

既存のプラグインを監査する際、欠陥に見えるものが必ずしも実際の欠陥とは限りません。以前のリファクタリングで意図的に生じた結果である可能性があります。典型例は、肥大化したオーケストレーターを簡素化するリファクタリングで、サンプルブロックが削除されたケースです。後続の監査で再追加を推奨すると、リファクタリングを元に戻すことになります。

監査レポートにエージェントやスキルに関する指摘を記載する前に、次の3つの質問で意図を確認してください。

1. 語数の区分 — エージェント／スキルの現在のサイズを踏まえると、見かけ上の欠陥は本当に欠陥ですか。それとも設計上の対象外ですか？
2. Git のログ — 該当コンテンツは最近、意図的に削除されましたか？リファクタリングのコミットを確認してください。
3. バリデーターの出力 — scripts/validate_plugins.py はその項目を指摘しますか？指摘しない場合は、監査でバリデーターより厳しい独自のルールを作らないでください。

3つすべての回答が「実際の欠陥」である場合に限り、修正リストに含めてください。詳しい理由、「意図的に削除された」パターンの監査時に注意すべき幅広いリスト、作成時の確認と監査時の確認の違いについては、agent-development/references/validation-and-audits.md を参照してください。

基本的な確認に使う1行の grep コマンド

プラグインのディレクトリから実行してください。何らかの出力があれば、指摘事項となります。

bash/macOS/Linux の場合：

grep -L "^---" skills/*/SKILL.md                                            # zero-frontmatter skills (P0)
grep -l "^agent: true" agents/*.md                                          # deprecated agents (P0)
grep -L "<example>" agents/*.md                                             # agents with no <example> blocks - cross-check body word count before flagging (lean orchestrators under 2,500 words are exempt; see agent-development tier table)
grep -L "PROACTIVELY activate for:" skills/*/SKILL.md                       # skills missing trigger enumeration (P1)
grep -L "Provides:" skills/*/SKILL.md                                       # skills missing capability list (P1)
grep -L "^model: inherit" agents/*.md                                       # agents not inheriting model (P2)
grep -l "MANDATORY: Always Use Backslashes" agents/*.md skills/*/SKILL.md   # Windows boilerplate in YAML (P0)

PowerShell（Windows）の場合、references/audit-greps.md に同等の一括チェック（プローブ1～7）と、肯定的な兆候を検証するクエリがあります。