the one line 95% of agent skills are missing一句话总结：95% 的智能体技能都存在缺失

A skill's description routes activation. The agent reads that field to decide whether to load the skill. A narrow description misses relevant prompts. A broad description intercepts unrelated work. Both failures produce no error.技能描述决定了其激活方式。智能体会读取该字段来决定是否加载此技能。描述过于狭窄会导致错过相关的提示；描述过于宽泛则会干扰无关的工作。但这两种失败情况都不会报错。

I pulled 200 public SKILL.md files from GitHub and ran them through tripwire's lint engine. The results:我从 GitHub 上拉取了 200 个公开的 SKILL.md 文件，并使用 tripwire 的 lint 引擎进行了扫描。结果如下：

Among 171 valid skills, 163 omit when the agent should load them. They describe what the skill is ("a helper for writing tests") and omit the activation cases ("use when the user adds tests, is looking at a failing test, or mentions coverage"). Authors ship a label and leave the routing signal weak.在 171 个有效的技能中，有 163 个遗漏了智能体应在何时加载它们的说明。它们只描述了技能是什么（例如“编写测试的助手”），却忽略了激活条件（例如“当用户添加测试、查看失败的测试或提到覆盖率时使用”）。作者只给出了标签，却削弱了路由信号。

The scan found other failures:扫描还发现了其他问题：

• 6 skills contain invalid YAML frontmatter: unquoted colons and stray quotes cause the loader to reject the file. My scanner crashed on the first one, so I changed it to count parse failures.6 个技能包含无效的 YAML frontmatter：未加引号的冒号和多余的引号导致加载程序拒绝读取文件。我的扫描器在遇到第一个错误时就崩溃了，所以我将其改为统计解析失败的数量。
• 20 stuff code fences into the description field. 13 leave TODO/placeholder text in.20 个在描述字段中塞入了代码块。13 个留下了 TODO 或占位符文本。
• 11 use non-kebab-case names.11 个使用了非 kebab-case 命名。

what the scan can prove扫描所能证明的结论

Tripwire classifies a missing "Use when…" line as a convention failure. Anthropic recommends the pattern because it sharpens activation. A static scan measures the text and cannot prove that a specific skill misfires in a live session. That proof requires a prompt matrix and real agent runs. Tripwire supports those runs; this post covers the free lint check.Tripwire 将缺少“使用场景……”（Use when…）这一行视为惯例错误。Anthropic 推荐这种模式，因为它能增强激活的精准度。静态扫描可以分析文本，但无法证明某个特定技能在实际运行中会触发错误。要证明这一点，需要通过提示矩阵和真实的智能体运行测试。Tripwire 支持这些运行测试；本文主要介绍免费的 lint 检查功能。

The defensible claim is: 95% of published skills leave their activation signal weaker than the recommended convention.可以明确的结论是：95% 的已发布技能，其激活信号都弱于推荐的规范。

why the miss repeats为什么这种遗漏反复出现

The Agent Skills specification opened in December 2025. Within about 90 days, 30+ agent tools supported it, including Codex CLI, Gemini CLI, VS Code, Cursor, and Goose. skills.sh lists about 90,000 skills. The routing field remains a freeform string with no compiler, test, or editor warning. Authors get no feedback when it drifts.Agent Skills 规范于 2025 年 12 月发布。在大约 90 天内，已有 30 多种智能体工具支持该规范，包括 Codex CLI、Gemini CLI、VS Code、Cursor 和 Goose。skills.sh 上列出了约 90,000 个技能。路由字段仍然是一个自由文本字符串，没有任何编译器、测试或编辑器警告。当该字段偏离规范时，作者无法获得任何反馈。

Tripwire adds the missing checks: lint for the file and agent runs that can gate a PR on activation behavior.Tripwire 补充了这些缺失的检查：包括对文件的 lint 检查，以及可以根据激活行为来拦截 PR 的智能体运行测试。

Try it on your own skill: paste a SKILL.md into tripwire.bharath.sh and inspect the result. Or run:试试你自己的技能：将 SKILL.md 粘贴到 tripwire.bharath.sh 并查看结果。或者运行：

npx tripwire-skills lint ./skills/yours/SKILL.md