skill-selector

技能选择器

添加技能占用磁盘空间不多，但会占用上下文。请谨慎选择。

此技能将两个关注点分开处理：

1. 从精选目录中选择 — 快速、经过取舍，通常足够。
2. 搜索并评估 — 覆盖面更广、速度更慢，仅在第 1 阶段不适用时使用。

请将两者作为不同的步骤执行。目录中的技能都已预先审核。目录外的技能未经审核，采用前必须明确评估。

适用场景

• 启动新项目／新仓库，并希望为其配备合适的技能
• 开发过程中发现某类任务会反复出现（突然需要 Playwright，突然需要发布自动化）
• 斜杠命令或其他技能提示需要一个尚未安装的下游技能

不适用的场景：

• 不会重复的一次性任务 — 直接处理；不要安装一个再也不会触发的技能
• 项目的 apm.yml 已列出相关技能 — 搜索前先重新检查

阶段 1 — 精选目录

目录位于 references/catalog.md。目录按项目特征（语言／工具／流程）分组，并内嵌 apm install 字符串。

工作流：

1. 阅读 references/catalog.md。
2. 从以下三个来源识别项目信号：
   • 仓库文件：package.json（Node）、moon.mod.json（MoonBit）、gleam.toml（Gleam）、flake.nix（Nix）、.github/workflows/（CI）、Playwright 配置、dotenvx 密钥库。
   • 用户明确表达的意图：消息中的线索，例如“我们计划部署到 X”“我们之后会发布一个小型 npm 实用工具”。
   • CLAUDE.md 中的强制要求：用户级 ~/.claude/CLAUDE.md 或项目级 CLAUDE.md 中的持久规则（例如“任务运行器：justfile”“lint：ast-grep”），即使场景文本未提及，也应视为信号。若强制要求与明确表达的意图相冲突，应在安装前向用户指出。在提案中明确标注由强制要求驱动的条目（例如 # 来自 ~/.claude/CLAUDE.md：任务运行器 = justfile），以免审核者误以为这些条目是凑数的。
3. 安装前征求用户确认——提出方案，让用户删减。默认少选技能，而不是多选。每项技能都会在每次对话中占用上下文。
   • 非交互场景（子 Agent 调度、脚本自动化、批处理）：将提案作为交付内容输出，然后停止。由调用方删减。不要停下来等待不会到来的确认。
   • 正在使用某种语言的启发式规则：如果用户正在用某种语言编写代码，且目录中有对应的 <lang>-practice 技能（例如 moonbit-practice、gleam-practice），则将其纳入。如果用户只是使用该语言编写的单个绑定或依赖，则暂缓纳入。
   • 平台名称注意事项：当目录条目的描述提到特定的 CI 提供商／运行时／云平台时：
     • 项目平台匹配：直接采用。无需重新阅读底层的 SKILL.md；目录条目已回答这一问题。
     • 项目平台不同：在决定前阅读底层的 SKILL.md。核心能力仍可能适用——为该核心能力安装，并注明“集成适配不适用”。仅因平台不匹配而跳过是错误的。
     • 无法读取底层的 SKILL.md（没有本地安装、上游克隆或网络）：不要默默跳过检查。在提案中明确说明不确定性——例如注明“根据目录描述采用 <skill>；未查阅 SKILL.md，因此尚未核实核心能力与集成适配的区分。”用户随后可以决定是否在确定安装前核实。若默默省略核实，就会留下后续无法弥补的问题（采用了错误的技能，或拒绝了可用的技能）。
   • 范围外条目：目录中标记为 (out-of-band) 的条目无法通过公共 APM 安装（例如 chezmoi-local、需许可的条目等）。如果项目可从中受益，可在说明文字中提及，但不要将其放入 apm.yml。
4. 通过 APM 安装。先阅读 apm-usage，以确认 apm.yml 的准确语法——清单格式并不简单，不能仅凭此技能推断字段名称。
   • 项目范围：编辑 apm.yml，运行 apm install。提交 apm.lock.yaml。
   • 全局范围：apm install -g <repo>/<path>，并在 ~/.apm/apm.yml 中验证。
   • 必须声明 targets:。 如果仓库根目录没有标记目录（.claude/／.github/／等），APM 0.12+ 不会回退到默认目标；没有目标时，apm install 会报错并要求明确选择。无条件在 apm.yml 中写入 targets: [claude]（或对应的宿主框架）；不要依赖目录自动检测。
   • targets: 不会严格限制部署目录。 即使设置了 targets: [claude]，APM 0.12+ 也可能同时写入 .agents/skills/ 和 .claude/skills/。检查 apm install 的输出（Skill integrated -> ...），并将列出的每个路径都视为下文 gitignore 决策中的部署目标。
   • 固定版本：目录条目不包含标签。提交 apm.yml 前，通过 apm view <repo>（或查看上游仓库的发布页面）解析出具体的标签或 SHA。浮动引用列在“常见错误”中。
5. 在首次提交前决定 gitignore 策略。 apm install 会自动将 apm_modules/ 添加到 .gitignore，但不会添加部署目标。选择一种策略并贯彻执行：
   • 提交部署目标（.claude/skills/、.agents/skills/ 等）：仓库内容完整，队友／CI 克隆后无需运行 apm install。代价：文件数量会大幅增加（在近期一次 utels 安装中，7 项技能约有 700 个文件）。适用于队友可能没有 APM，或希望技能内容可在 PR 中审核的情况。
   • 将部署目标加入 gitignore：仓库更精简；队友克隆后运行 apm install --frozen-lockfile。添加 apm install 输出的准确路径（例如 .claude/skills/、.agents/skills/）。注意：如果项目也在同一目录下保留本地技能（.claude/skills/<local-skill>/），则只将 APM 管理的子路径加入 gitignore，不要忽略整个目录。
   • 无论如何都要提交 apm.yml 和 apm.lock.yaml。没有锁定文件，安装就无法复现——部署目标的 gitignore 选择只会影响生成的产物是否纳入 Git。
   • 首次将 APM 技能安装到仓库时，向用户提出这一选择。不要擅自决定——文件数量膨胀与克隆后安装都是合理选项，具体取舍取决于仓库。
6. 如果仍有需求未满足，则升级到阶段 2。不要跳过阶段 1——即使你已经在脑中构思搜索词，先扫描目录的成本也更低。

阶段 2 — 搜索与评估（委托给 skill-finder）

阶段 2 由 skill-finder 技能负责。仅当以下条件全部满足时才触发：

• 阶段 1 没有候选项（已扫描目录，约 30 秒内没有匹配的条目）。
• 需求是反复出现的，而不是一次性的设置任务。一次性脚手架搭建（Vite/React 初始化、单次配置转换、临时数据迁移）应直接处理。
• 需求明确表现为当前痛点或近期任务，而不只是一个背景信号。仓库中存在一个 Rust 服务，但它当前并未引发与技能相关的问题，这本身不足以成为启动阶段 2 的理由——等反复出现的需求显现后再说。

如果三项中有任何一项不满足，就不要采取行动。升级处理前，请重新阅读上文的“何时不应使用”部分。

运行阶段 2：告诉用户“阶段 1 目录中没有合适项；要我调用 skill-finder 进行跨来源搜索吗？”只有得到明确同意后才能继续。skill-finder 会执行跨来源调查（Anthropic 官方 → claude-skill-registry → VoltAgent → ComposioHQ → Superpowers → GitHub topic），应用相同的评估标准，并通过强制的 waxa 评估把关采纳流程。不要在此处重复这套工作流。

阶段边界 — 不要混淆

两个阶段解决的是不同问题：

• 阶段 1 以覆盖面换取可信度。目录经过精心整理；请信任它。
• 阶段 2 以可信度换取覆盖面。通过明确评估来弥补。

常见错误：一开始就进入阶段 2（“我来 grep 一下 GitHub，找个 Playwright 技能”），而阶段 1 已经有 playwright-test。务必先阅读目录。

相反的错误：目录确实没有合适项，却硬要在阶段 1 中凑一个。如果扫描约 30 秒后仍没有匹配条目，就升级处理——不要用相近但不完全合适的技能填充安装列表。

目录维护

• 目录是此技能的一部分。当 mizchi/skills（以及其中引用的上游技能仓库）新增或移除技能时，请保持目录同步。
• 通过阶段 2（skill-finder）发现的技能，在至少 2 个项目中使用且未出现问题，并通过其 waxa 评估后，可以收录进目录。
• 如果目录似乎过时，转而使用 skill-finder 之前，请先与 mizchi/skills README 交叉核对。

常见错误

错误	修正
“以防万一”就安装技能	不要这样做。每个技能都会占用每次对话的上下文。只有近期任务确实需要时才安装。
跳过目录，直接搜索 GitHub	先重新阅读目录。目录的存在就是为了避免这种情况。
未经测试就采纳阶段 2 的技能	skill-finder 要求在采纳前通过 waxa 评估。不要绕过这一步——描述可能不实。
在项目范围的 apm.yml 中使用浮动引用	固定到 tag 或 SHA。功能开发期间版本漂移只会带来无尽的调试麻烦。
每季度重新评估同一个已拒绝的技能	在仓库中记录拒绝原因。不要重复搜索已覆盖的内容。
默默提交（或默默添加到 gitignore）APM 部署目标	明确说明选择——参见第 5 步。默认提交可能导致仓库膨胀；默认忽略则可能让没有 APM 的队友无法使用。
以为 targets: [claude] 会让部署路径仅位于 .claude/skills/ 下	APM 0.12+ 也可能写入 .agents/skills/。阅读 apm install 的输出，并将其中列出的每个路径都视为部署目标。
认为阶段 1 目录面面俱到	如果约 30 秒内没有匹配项，就升级到阶段 2。不要牵强附会。

相关内容

• skill-finder — 阶段 2 负责人；当目录中没有合适项时，执行跨来源调查并通过 waxa 评估把关
• apm-usage — 实际的 apm install 语法和清单格式
• empirical-prompt-tuning — 采纳候选技能前的测试方法
• superpowers:writing-skills — 没有现有技能合适时，编写新技能，而不是采纳不合适的技能
• chezmoi-management — 适用于必须保持私有的技能（APM 与 chezmoi 的边界）