skill-finder

技能查找器

采用精选目录以外找到的技能，存在目录内流程不会遇到的两种失败模式：

1. 内容质量低 —— 各注册库的审核标准差异很大；有些只是 SEO 抓取结果。
2. 对注册库缺乏了解 —— Tier-1 官方来源可能已经能满足需求；一开始就跳到 GitHub grep 会浪费精力，还会带来更嘈杂的列表。

此技能旨在让跨来源搜索有章可循，并拒绝采用任何未通过 waxa 评估的技能。

何时调用

仅在用户明确提出请求时调用。触发短语：

• “查找一个 <X> 技能”
• “有没有适用于 <X> 的技能？”
• “在采用 <owner/repo> 作为技能前对其进行评估”
• “在各注册库中搜索 <X>”

何时不要使用：

• 目录中已有合适选项 → 立即停止，并告知用户改用 skill-selector Phase 1。不要继续搜索 Tier 1-4，不要提出安装步骤，也不要调查其他来源。即使外部技能可能改进目录中的技能，现有选项就是答案；请遵循 Phase 1。
• 一次性任务，没有重复执行的可能 → 直接解决；不要采用一个只会触发一次的技能。
• 用户没有要求发现技能 → 作为元技能，本技能绝不会自动触发（参见用户级 CLAUDE.md 中的“技能使用方针”）。

预检（必须首先执行）

在做任何其他事情之前，根据用户提出的需求检查 skill-selector/references/catalog.md 中的条目。如果有任何条目匹配：

1. 告知用户匹配的目录条目。
2. 建议用户调用 skill-selector（Phase 1）进行安装。
3. 停止。 不要运行下方的工作流。不要调查 Tier 1+ 来源。

只有在阅读约 30 秒后，目录检查仍未找到匹配项时，才可继续执行此检查。

来源

优先级分层。务必从最高优先级开始，只有上一级没有合适选项时才继续。

Tier	来源	形式	备注
1	anthropics/skills	GitHub 仓库，约 30 个第一方技能	信任度最高。安装方式：apm install anthropics/skills/skills/<name>（该仓库将技能放在 skills/ 目录下）。
1	anthropics/claude-plugins-official	插件市场	官方插件（frontend-design / mcp-server-dev / code-review / ralph-loop / external_plugins/...）。
2	majiayu000/claude-skill-registry	每日抓取、去重并进行安全扫描的跨来源索引	最佳发现中心。路径格式 owner/repo/skills/name 可直接转换为 APM。
2	VoltAgent/awesome-agent-skills	按组织分组的 awesome 列表（MIT，持续维护）	每个条目都通过 officialskills.sh 跳转；采用前请解析到对应的 GitHub 仓库。
3	ComposioHQ/awesome-claude-skills	Awesome 列表，收录范围更广、筛选更宽松	将条目视为候选项，而非背书推荐。
3	obra/superpowers	技能包，侧重方法论（TDD / 子 Agent / 头脑风暴）	质量很高，但有其特定理念；请仔细检查是否适用。
4	GitHub topic:claude-skill / topic:agent-skills / path:**/SKILL.md	原始搜索	最后手段。按最近更新排序，而非按星标数（星标最多的仓库通常是 awesome 列表，而非技能）。
NG	agent-skills.cc	SEO 抓取，只有星标数作为信号，与 APM 不兼容	不要从此处获取来源。可将其用作别名查询，以查找对应的 GitHub 仓库，但绝不能作为主要推荐来源。

工作流

0. 预检目录（见上文）。 如果 skill-selector/references/catalog.md 中有匹配项，请停止并交由 skill-selector 处理。只有在没有目录条目匹配时，才继续第 0 步之后的流程。
1. 明确重复出现的需求。 只有针对反复出现的任务类型，才有理由采用技能。如果用户说不出具体任务类型，就不要采用；直接在当前任务中解决。
2. 自上而下检索。 优先查看 Tier 1。遇到第一个可用项就停止；如果 Tier 1 已匹配，就不要调查更低层级。记录每个候选项的：技能名称、解析后的 GitHub URL、一句话描述、最后更新日期、许可证。
3. 应用评估标准。 候选项只有在以下七个维度都可接受时才算通过：
   • 匹配度——该技能的“使用场景”是否确实符合项目任务？重新阅读描述，不要只看标题。
   • 非冗余性——项目中已安装的技能集是否已覆盖此需求？与技能栈中已有技能重叠的候选项，即使“匹配度 ✓”，也仍应拒绝（或者最多仅固定到一个确实缺少相关覆盖的项目）。常见重叠组合：创建技能的技能与 superpowers:writing-skills + empirical-prompt-tuning + waxa-eval；测试技能与 playwright-test；dotfile 技能与 chezmoi-management。冗余技能每次对话都会占用上下文，却没有独特收益。
   • 维护情况——最近是否有提交？上游是否有明显活动？
   • 许可证——是否提供 SPDX 标识，且与使用该技能的项目兼容？
   • Frontmatter 状况——name 是否与目录名一致？描述是否不超过 1024 个字符，且采用触发条件的表述形式（遵循 superpowers:writing-skills 的 CSO）。
   • 正文质量——是否明确说明“何时不应使用”？是否提供具体模式，而非模糊建议？
   • 占用开销——正文长度、引用内容是按需加载还是始终加载、跨技能依赖。
4. waxa 审计（建议）。 在耗用评估门槛的预算前，运行 npx @mizchi/waxa audit <candidate-skill-dir>，以低成本发现结构问题：frontmatter 格式、正文长度、缺少“何时不应使用”、可疑脚本、缺少 LICENSE，以及 apm audit 的隐藏 Unicode（提示词注入）扫描。审计报错的候选项很可能应被拒绝，无需耗费 LLM 时间进行评估门槛测试。
5. waxa 评估门槛（必须）。 不经过实证评估就采用技能，正是此技能要防止的失败模式。对每个入围候选项：
   • 临时安装：在沙盒项目中运行 apm install <owner>/<repo>/skills/<name>（或为本地审计创建符号链接）。
   • 编写 1-2 个符合项目实际重复任务的示例 tasks/*.yaml。可参考 skill-selector/evals/ 和 nix-setup/evals/（waxa 0.2.0 的技能本地目录布局）中的可用模板。
   • 运行 waxa run，每项任务至少设置 trials_per_task: 2。
   • 反复迭代（waxa iterate），直到账本收敛。收敛 = 连续 2 次运行没有未明确点（参见 empirical-prompt-tuning）。
   • 如果经过 2 次迭代后未明确点仍然存在，且没有减少趋势 → 视为发散，予以拒绝。
6. 作出决定并固定版本。 采用时必须固定版本；固定版本不容妥协。
   • 提升至目录——通过评估且已在 2 个以上项目中使用、没有问题 → 提议将其加入 skill-selector/references/catalog.md，并说明应触发它的项目特征。
   • 固定到项目——适用于单个项目；将其添加到该项目的 apm.yml，使用通过 apm view <repo>（或上游发布页面）解析出的标签或 SHA。固定到 waxa 评估通过时使用的确切引用——先完成评估，再采用，并固定到经过评估的引用。生产项目禁止使用浮动引用（main、master、HEAD）。
   • 拒绝——在 references/rejection-log.md（本技能）和／或项目自己的 docs/skills-rejected.md 中记录原因，避免同一候选项每季度都被重新评估。常见拒绝原因：缺少许可证、正文质量未达最低标准、未通过非冗余性评估（已由已安装的技能栈覆盖），或维护情况不足。
7. 分叉并修复路径。 如果候选项接近合格但仍有不足，优先将其分叉到 mizchi/skills/<name>（或项目的本地技能目录）并重新调整，而不是在调用点绕过其缺陷。记录差异，以便通过上游 PR 合并修正。

特定来源的解析说明

• anthropics/skills：技能位于 skills/<name> 下。安装字符串：apm install anthropics/skills/skills/<name>（路径包含“skills/skills”——这不是笔误）。

• anthropics/claude-plugins-official：包含 external_plugins/（asana、linear、playwright、serena、laravel-boost、github、gitlab、firebase、terraform）。这些是插件，不是原始技能——将其作为 APM 依赖项之前，请确认插件清单公开了 SKILL.md。

• majiayu000/claude-skill-registry：自带 sk CLI；你不需要使用它。知道路径后，apm install owner/repo/skills/name 即可正常工作。仅使用注册表的网页 UI / 数据文件进行发现。

• VoltAgent/awesome-agent-skills：README 按组织分组（Anthropic / Stripe / HashiCorp / Cloudflare / Sentry 等）。使用以下命令提取条目：

  curl -sL https://raw.githubusercontent.com/VoltAgent/awesome-agent-skills/main/README.md \
    | grep -oE '\[[^]]+\]\(https?://officialskills\.sh[^)]+\)'
  

  每个 officialskills.sh URL 都会指向一个 GitHub 仓库；评估之前，请先前往该仓库。

• GitHub 主题搜索：使用 API。topic:claude-skill（1.4k 个仓库）和 topic:agent-skills（4.3k 个仓库）结果都很嘈杂——根据是否存在 SKILL.md 和近期活动进行筛选。path:SKILL.md 限定条件有助于缩小范围。超过 Tier 3 后，星标数基本没有参考价值（星标数最高的仓库都是精选列表，而非技能）。

waxa 评估模板

对于 <owner>/<repo>/skills/<name> 中的候选技能，搭建以下结构：

evals/
└── <name>/
    ├── eval.yaml
    └── tasks/
        ├── scenario-typical.yaml
        └── scenario-edge.yaml

eval.yaml 骨架：

name: <name>-eval
skill: <name>
version: "0.1"

config:
  trials_per_task: 2
  timeout_seconds: 180
  parallel: false
  executor: claude-cli   # mock for smoke; claude-cli for real eval
  model: claude-opus-4-8

graders:
  - name: <task-specific>
    type: text | code | llm | self_report
    config: { ... }

tasks:
  - "tasks/*.yaml"

本仓库中可用的参考示例：skill-selector/evals/eval.yaml、nix-setup/evals/eval.yaml（来自 waxa 0.2.0 的技能本地布局）。

常见错误

错误	修正方法
并行调查所有层级	从上往下调查。找到首个合适项后就停止。
跳过预检目录检查	务必先检查 skill-selector/references/catalog.md。如果其中已覆盖需求，应立即交由其处理——不要继续调查 Tier 1 及以上层级。最常见的错误升级项是 playwright-test / cloudflare-deploy / gh-fix-ci，需要特别留意。
仅因“Fit ✓”就采用	是否冗余是一个独立维度。即使某个技能符合用户明确提出的需求，但与已安装的技能重叠（例如 anthropic 的 skill-creator 与 superpowers:writing-skills + empirical-prompt-tuning + waxa-eval 重叠），也应拒绝。成本是每次对话占用的上下文；收益必须是独有的。
拒绝时跳过 references/rejection-log.md	记录原因只需 30 秒，可避免 3 个月后因星标数增加而重新评估同一候选项。日志是技能查找流程的持久记录，就像 waxa-eval 的评估台账一样。
将 agent-skills.cc 列为推荐来源	该来源是 SEO 抓取结果；仅可用于查询 GitHub 别名。切勿将其作为主要推荐来源。
跳过 waxa 评估（“README 看起来没问题”）	这是禁止的。未经评估就采用，正是此技能旨在防止的失败情况。
固定到 main / master	使用 apm view <repo> 解析标签或 SHA，并明确固定到该版本。
将组织成员身份视为质量保证	知名组织下的仓库并非自动可信；仍须按标准评估。Anthropic 发布的技能是少数例外。
重新评估之前已拒绝的技能	先检查 docs/skills-rejected.md。记录拒绝原因可避免每季度反复评估。
未扫过 Tier 1-3 就直接查看 Tier 4	成本差异很大：GitHub 搜索结果嘈杂，而精选层级已经过预筛选。

相关内容

• skill-selector — Phase 1 目录选择。**务必先运行此技能。**如果 Phase 1 已覆盖需求，请勿调用 skill-finder。
• apm-usage — 安装 / 固定步骤所用的 apm.yml 语法
• empirical-prompt-tuning — waxa 评估门槛背后的收敛 / 发散语义
• superpowers:writing-skills — 没有候选项通过评估标准时，自己编写技能，而不是勉强接受不合适的选项