triggering-reliability

导致触发失败的常见错误

本技能是 Claude Code Agent 和技能触发失败原因的参考目录。以下每种错误都在实际插件中出现过。发布任何插件前，请将此目录作为检查清单；现有插件安装成功却毫无反应时，也应首先查阅此目录。

快速排查：症状与最可能的原因

症状	最可能的原因
技能目录存在，但从未加载	缺少 YAML frontmatter（文件以 # 而不是 --- 开头）
Agent 文件存在，但无法按名称调用	使用了已弃用的 agent: true 标记，且没有 name: 字段
即使查询很明显，Agent 也很少触发	缺少 <example> 块，或描述只写了抽象能力
技能触发不稳定	描述写了它能做什么（WHAT），而不是何时使用它（WHEN）
多个技能争抢同一查询	描述中的触发短语重叠
Agent 描述会匹配到通用且无关的查询	YAML description: 中的 Windows/文档模板内容会干扰路由
Agent 使用了错误的模型	缺少 model: 字段，或将其硬编码而非设为 inherit

九种典型反模式（摘要）

每种反模式的完整症状／根本原因／修复说明见 references/anti-patterns-catalog.md。速查表：

#	反模式	严重级别	一句话修复方法
1	完全没有 frontmatter 的技能——缺少 ---	P0	添加规范的 YAML frontmatter（name:、description:）
2	已弃用的 agent: true 标记	P0	替换为 name: <kebab>
3	抽象的“Use this agent for X”描述	P1	改写为 PROACTIVELY activate for: (1)... (N)...，并添加 Provides:
4	描述写了能做什么（WHAT），而非何时使用（WHEN）	P1	改为以用户意图为依据的触发条件；以 PROACTIVELY activate for: 开头
5	超过 2,500 个单词的 Agent 缺少 <example> 块	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。本文件底部的 规范检查的一行式 grep 命令 中也列出了快速单行命令。

按错误优先级修复

1. P0 - 零 frontmatter 的技能和 agent: true 的 Agent（不可见／无法正常工作）。
2. P0 - YAML 中的 Windows／文档模板内容（会直接干扰路由）。
3. P1 - 支持多个技能的臃肿 Agent 缺少 <example> 块（正文超过 2,500 个单词）。低于 2,500 个单词阈值的精简型编排器按设计不受此限制。
4. P1 - 描述缺少 PROACTIVELY activate for: / Provides: 条目。
5. P2 - 元数据规范性（model: inherit、color:、精简 tools:）。
6. P2 - 触发短语重叠审查与消歧。

按优先级顺序修复——存在 P0 错误时，不要花时间处理 P2。

严重性级别与描述长度限制

报告问题时，使用 P0 / P1 / P2 级别（插件无法运行／路由不可靠／润色）。描述长度受三项限制约束：API 规范的硬上限为 1024 个字符，Claude 在路由时可见的列表上限为 1536 个字符，以及所有已安装技能合计约占 1% 上下文窗口的预算。

各严重性级别的完整表格及具体示例、包含数值和含义的描述长度限制表，以及编写目标：参见 references/severity-and-limits.md。

提交前大小与 DRY 检查（必须执行）

向 SKILL.md 或参考文件添加任何内容前，必须通过以下两项检查：

1. 大小检查 — 使用 wc -w（或 PowerShell Measure-Object -Word）统计目标文件的字数。如果文件字数在 2,800–3,000 之间，必须先将参考资料类内容提取到 references/，再进行添加。超过 3,000 个单词即表示文件已不合格；应先提取内容，使其低于 2,000 个单词，再进行其他操作。
2. DRY 检查 — 使用 grep -rn（或 Select-String）在 skills/、agents/、commands/、README.md 中搜索候选内容块的第一条独特语句。只要在其他位置找到一处，就必须将内容块提取到 skills/_shared/（跨技能共享）或 references/（单个技能专用），而不是直接粘贴。

完整决策表、bash 和 PowerShell 的精确命令，以及组合工作流：参见 references/size-and-dry-gates.md。

发布前标准检查清单

完整的 26 项检查清单（包括 plugin.json 格式、Agent 和技能 frontmatter、描述内容、DRY 检查 grep、代码示例检查、大小上限、NOTICES.md 和 marketplace.json 注册）位于 references/pre-publish-checklist.md。发布前请逐项检查。

代码示例健全性检查

两个缺陷经常悄悄混入围栏代码块中，导致读者无法正常使用：

1. 智能标点（弯引号、长破折号/短破折号、Unicode 省略号）出现在围栏代码块中，会破坏复制粘贴操作——grep 无法匹配，JSON 无法解析，Shell 引号也会失效。在启用了自动更正的编辑器中输入内容，或从文字处理软件中粘贴内容时，作者可能会不经意地引入这些字符。
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):，并且围栏的语言标签与之匹配。

本仓库的主要 Shell 是 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——仅当 Agent 正文超过 2,500 个单词时触发
Agent missing model: inherit	错误	反模式 7
Description / SKILL.md 长度检查	错误/警告	反模式 9 + 长度上限

完整的验证器规则索引（Agent、技能和插件级别）以及已知的验证器缺口，位于 agent-development/references/validation-and-audits.md。请确保该表与验证器代码保持同步。

审计注意事项：推荐修复前先核查意图

审计现有插件时，表面上的缺陷未必是真正的缺陷——它可能是先前重构有意产生的结果。典型示例：从臃肿架构转为精简架构的重构中，精简编排器里的示例块被移除。后续审计若建议将其加回来，就会撤销这项重构。

在审计报告中列出任何 Agent 或技能相关问题之前，请先进行以下三项意图核查：

1. 字数级别——Agent／技能当前的规模是否让表面上的缺陷构成真正的缺陷，还是按设计豁免？
2. Git 日志——缺失的内容是否是近期有意移除的？请查找重构提交。
3. 验证器输出——scripts/validate_plugins.py 是否将其标记为问题？如果没有，审计时就不要擅自制定比验证器更严格的规则。

只有三项核查的结论都为“真正的缺陷”，才应将其列入修复清单。完整的理由说明、需要留意的其他“有意移除”模式，以及编写与审计之间的差异，请参阅：agent-development/references/validation-and-audits.md。

典型核查用单行 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），以及用于验证正向信号的查询。