skillcheck

skillcheck

找出哪个技能抢走了请求。

你的技能通过了评测。在你自己的配置中，和你安装的其他所有内容一起运行时，它会触发吗？

官方技能评测会在干净的环境中加载一个技能。实际使用时，它会和数十个其他技能及插件一起运行，其中一个可能会悄悄抢走请求。在作者的配置中，某些提示词在独立的 claude plugin eval 中触发了 21/21 次，但在真实运行环境中有 5 次未能触发。

skillcheck 会在你实际安装的所有内容中，通过真实的 claude 和 codex CLI 运行提示词，并报告触发了哪个技能、哪个技能抢走了请求、每条提示词的触发稳定性，以及描述修改是否有效。

新功能：安装技能前先检查。 preflight 会在临时文件夹中分别运行你现有技能的提示词（有和没有新技能），告诉你新技能会从哪些已安装技能那里抢走请求。不会触碰你的真实技能文件夹。词语重叠只能提示可能的竞争者（措辞重叠很少的窄范围技能也可能抢走请求），因此请用 --skills 指定你关心的技能：

python3 skillcheck.py preflight path/to/new-skill            # instant: name clashes, likely rivals, listing size
python3 skillcheck.py preflight path/to/new-skill --measure  # real runs: your skills' fire rate without → with it
python3 skillcheck.py preflight path/to/new-skill --measure --skills my-a,my-b   # pick which of yours to measure

报告示例：两个技能的触发率从 0/4 和 1/4 提升到了 4/4，原因是重写了它们的描述。

安装

作为 Claude Code 插件安装（skillcheck 技能会引导你完成扫描 → 运行 → 修复 → 再次运行）：

/plugin install skillcheck --marketplace Noem836/skillcheck

也可以作为单个文件使用（Python 3 标准库；如果已安装 PyYAML，则会用于检查 frontmatter）。请固定到某个版本，并校验其哈希值：

curl -fsSLO https://raw.githubusercontent.com/Noem836/skillcheck/v0.1.0/skillcheck.py
shasum -a 256 skillcheck.py   # compare with the release notes

使用

python3 skillcheck.py scan                          # static checks, no model calls
python3 skillcheck.py gen --skills my-skill         # draft should-fire / near-miss prompts → suite.json
python3 skillcheck.py run --agent claude --tag before --runs 3
python3 skillcheck.py report --tag before           # fire rate, false fires, who took it
# edit the description, then
python3 skillcheck.py run --agent claude --tag after --runs 3
python3 skillcheck.py compare --before before --after after
python3 skillcheck.py html --tag before,after       # one-file HTML report
python3 skillcheck.py upload --tag before,after     # optional share link

面向 AI Agent（远程 MCP，无需安装）

托管的只读 MCP 服务会对任何公开的 GitHub 仓库运行静态检查，适合在安装或发布技能包之前使用：

claude mcp add --transport http skillcheck https://skillcheck-d1d57e.fly.dev/mcp

工具：

• preflight_skill(github_url, installed)：安装技能前调用。传入用户已有的技能（名称和描述，Agent 可以从自己的技能列表中读取）。它会返回可能遮蔽已安装技能的名称冲突、最有可能从哪些已安装技能那里抢走请求，以及技能列表会增加多少内容。
• check_skill_repo(github_url) 会返回 frontmatter/YAML 错误、名称不匹配、描述过弱或仅包含斜杠的描述、嵌套的 SKILL.md 文件、重复名称，以及描述重叠到足以产生竞争的技能对。测量真实触发情况仍需使用 CLI，因为它会在你的配置中运行。

检查内容

• 发现：Claude Code（~/.claude/skills、.claude/skills、已启用的插件和 skillOverrides）以及 Codex（~/.agents/skills、~/.codex/skills、.agents/skills）
• 静态检查：缺少或损坏的 frontmatter、名称与文件夹不匹配、描述过短或过长、嵌套的 SKILL.md、仅包含斜杠的措辞、disable-model-invocation、重复名称
• 真实触发：每条提示词运行 N 次；记录首次加载的技能，然后停止运行
• 竞争情况：哪个其他技能抢走了本应触发的提示词，以及未触发的提示词被分配到了哪里

安全性

提示词套件和第三方技能可能包含提示词注入，因此运行受到严格限制： Claude 仅使用 --tools Skill 运行；Codex 使用 --ignore-user-config 运行，不进行网页搜索、不启用应用或插件，并使用只读沙箱。python3 check_isolation.py 会通过金丝雀文件验证这些限制。

运行使用你自己的 CLI 登录和订阅。除非你运行 upload，否则不会向任何地方发送数据；运行该命令时只会发送技能名称和命中/未命中记录，不会发送提示词文本。

报告服务器

server.py 是分享链接服务器（标准库 + sqlite）。check_web.py [url] 会对运行中的实例进行攻击测试（XSS、超大/过深的 JSON、慢速客户端、猜测 ID、伪造速率限制）。使用随附的 Dockerfile / fly.toml 部署。

常见问题

为什么我的 Claude Code 技能没有触发？ 通常是其他已安装的技能优先响应了请求，或者描述看起来只适用于斜杠命令（“use as /name”）。运行 scan，然后运行 run + report，查看 taken by 列。请参阅指南。

我的技能通过了 claude plugin eval，但在日常设置中不会触发。为什么？ 官方评估会在干净的环境中加载技能。skillcheck 则会在你实际安装的所有内容旁测量它。

我的哪个技能抢走了另一个技能的请求？ report 会针对每个技能列出：在其应触发提示词上，加载了哪些其他技能。

它支持 Codex CLI 吗？ 支持：run --agent codex。技能激活情况会从 codex exec --json 事件中读取的 SKILL.md 获取。

发布到市场之前，如何测试 SKILL.md 描述？ gen 会起草应触发和相近误触发提示词，run 进行测量，你进行编辑，然后 compare 显示前后对比。远程 MCP 可快速静态检查整个仓库。

它会把我的提示词或代码发送到任何地方吗？ 不会。运行时会在本地使用你自己的 CLI 登录。upload 是可选的，只会发送技能名称以及命中／未命中行。

限制

• 仅支持 Claude Code 和 Codex。Gemini CLI 和 Cursor：目前还无法可靠地读取激活情况，欢迎提交 PR。
• 每条提示词的运行大约需要一分钟；10 个技能 × 6 条提示词 × 3 次运行需要消耗数小时的订阅额度。

MIT 许可证。