一、背景：为什么要做这个 Skill

做这个 Skill 的初衷很直接，也很现实：功能开发时容易"顺手新建一个"，而不是先复用已有组件，造成组件库越来越臃肿。这件事对团队的伤害其实是复利型的：

• 重复组件越来越多；
• 维护成本越来越高；
• UI/交互一致性越来越差；
• AI 生成代码时也更容易继续复制混乱。

所以做这个 Skill 的目标不是"帮 AI 搜索一下"，而是：把"复用优先"的思考过程流程化，让 AI 在写代码前先走一遍"查索引 → 判断是否复用 → 命不中再新建"的路径。

二、想解决的不是搜索问题，而是“思考顺序”问题

一开始很容易把问题理解成："做个组件搜索工具给 AI 用就好了"。但实际落地后发现，真正的问题不是工具有没有，而是：

• AI 会不会主动用；
• AI 什么时候用；
• AI 用完之后是否还能回到项目上下文；
• AI 能不能稳定走同一条流程。

这和 Vercel 在他们的 agent 评测里观察到的现象很像：skills 本身不是没用，而是 agent 往往不会稳定触发；而把基础知识放进 AGENTS.md 这种"被动上下文"后，稳定性反而更高。Vercel 的实验里，默认 skill 触发并没有提升通过率，加入显式指令后才明显改善，而 AGENTS.md 文档索引方案表现更稳定。这给了我一个很关键的设计方向：先解决 AI 的"决策点"问题，再解决 AI 的"能力"问题。

三、核心设计思路：AGENTS.md + Hook + Skill（三层结构）

最终采用的是三层结构：

把"组件复用优先"的规则、组件索引入口、扫描后需要做的事情，放进 AGENTS.md（或同类常驻上下文机制）里。目的不是塞满文档，而是让 AI 每轮都知道：

• 这个仓库有组件复用机制；
• 默认应该先查可复用组件；
• 查不到再考虑新建；
• 扫描后还有描述补全流程需要继续执行。

这层解决的是：AI 根本不知道你有这套机制。不写进去，AI 主动使用 skill 的概率确实会很低（这点我踩过坑）。

如果运行环境支持 hooks（例如 Claude Code 的 UserPromptSubmit 支持在用户 prompt 处理前注入额外上下文），就可以做一层"意图路由增强"：在用户提到"组件复用 / 是否有现成组件 / 封装组件 / 查组件"等语义时，给 AI 注入提示，让它优先走组件复用流程。Claude 的文档明确写了 UserPromptSubmit 会在处理前触发，并且可通过 additionalContext 注入上下文。这层解决的是：AI 知道有 skill，但不一定想起来用。

Skill 不是只写说明文档，而是要提供：

• 明确的调用入口；
• 稳定的输出格式；
• 可执行脚本；
• 失败时的兜底逻辑。

OpenAI 的 Codex Skills 文档里提到 skills 是"渐进披露"机制：运行时先看到 skill 的元信息（尤其是 description），只有决定使用时才加载完整 SKILL.md；而且隐式触发高度依赖 description。这也是为什么 skill 的触发边界和描述要写得非常清楚。这层解决的是：AI 想用了，但执行过程不稳定。

四、这套 Skill 在源码里是怎么落地的（我的实现）

下面是我这次组件复用 Skill 的几个关键实现点：

我在 SKILL.md 里明确规定：Agent 必须调用统一入口find-component.js。这样做的原因很简单：

• 避免 AI 在多个脚本之间犹豫（scan-components、match-component、resolve-scope……）；
• 避免 AI 漏掉前置步骤（比如索引不存在时先扫描）；
• 避免 AI 调用路径不一致导致结果不稳定。

统一入口做了几件事（都在 find-component.js 里）：接收查询词（query）、仓库根路径（repoRoot）、当前聚焦路径（startDir）。

• 如果 components.csv 缺失，内部自动触发run-scan.js；
• 调用 resolve-scope 计算当前应用和允许搜索范围；
• 调用 match-component 做匹配排序；
• 命中时记录使用（用于后续加权）；
• 按固定 JSON 协议返回结果（成功/失败/无匹配/是否触发扫描等）。

这一步本质上是把分散逻辑聚合成"一个业务动作"："查一下有没有可复用组件"，而不是"先算 scope，再查 CSV，再排序，再补扫，再记 usage"。这对 AI 很关键。

在 monorepo 场景里，组件复用很容易踩两个坑：

• 只搜当前 app，漏掉根级共享组件；
• 全仓乱搜，结果太多太噪音。

所以我在 resolve-scope.js 里做了一个比较工程化的范围解析策略：

• 读取 pnpm-workspace.yaml 解析 workspace 包；
• 根据当前聚焦文件/目录反推 currentAppRoot；
• 再结合 root_scope_patterns（例如 apps/_share/、packages/ 等）构建允许范围；
• 最终形成一个搜索集合：当前应用 + 根作用域共享包。

如果没有聚焦子项目（比如 startDir 就是 repo root），则切换为全量 scope。这个设计很像人类工程师的查找策略：先看"我这个业务应用里有没有"，再看"全局共享有没有"，而不是直接在整个 monorepo 海里捞针。

组件匹配如果只做字符串包含，很快就会变成垃圾召回器。我在 match-component.js + fuzzy-match.js 里做了一个组合评分，核心包括：

• 名称精确/包含匹配；
• 模糊匹配（编辑距离）；
• Token 重叠；
• 首字母缩写匹配（例如 dlp 匹配 DateLinkPicker）；
• 当前应用加权（当前 app 的组件优先）；
• 使用频率加权（常用组件更靠前）；
• 来源质量加权（README 推断质量高于纯 inferred）；
• 存在性校验（文件不存在则降权/过滤）；
• 记录类型权重（组件优先于依赖）。

这一步的目标不是追求"算法先进"，而是让排序更符合团队真实使用习惯："更可能被复用的组件排在前面"。此外我还加了一个低分阈值（NO_MATCH_SCORE_THRESHOLD）：

• 如果最高分太低，就认为是噪音命中；
• 可以触发一次扫描后再查；
• 还是低分则按"无匹配"返回，不把噪音结果塞给 AI。

这个点很重要，因为 AI 一旦拿到一些低质量候选，很容易"将错就错"。

很多类似方案停在“扫一遍生成 CSV”，然后就过时了。我这次把扫描做成了 run-scan.js -> index-manager -> enrich 的流水线，核心考虑是持续维护：

run-scan.js 负责编排流程

• resolve-scope；
• updateIndex；
• 自动触发 autoEnrich（可配置）。

index-manager.js 负责索引更新策略

• 保留历史记录并合并；
• 根据 source_hash 跳过未变化组件；
• 记录 last-scan-changed-ids.json；
• 支持并行扫描（包数量较多时启用）；
• 对缺失文件支持标记 exists=0（在查找阶段也会回写）。

扫描后进入 Agent 富化（enrich）流程

• 读取 agent-enrich-prompts.json；
• 找出 summary 占位符项；
• 按 id 回到 components.csv；
• 读取源码/README；
• 生成 summary + keywords；
• 再通过 update-component-summary.js 写回。

更关键的是在配置里启用了：

• agent_mode_no_fallback = true。

也就是说，在 Agent 模式下不走规则引擎降级，而是要求 Agent 必须完成这一步。这其实就是"流程化思考"的精髓：不是建议，而是纳入主流程。

一个很容易被忽视的点是：查找命中后，我还记录了使用行为（usage-tracker）。这意味着系统不是静态的，它会逐步学习团队偏好：

• 哪些组件经常被复用；
• 哪些组件在某个 app 里更常出现；
• 哪些结果应该在排序中更靠前。

这是一种很轻量但非常实用的反馈机制——不需要搞复杂训练，也能提升 AI 下一次推荐质量。

五、这次实现里，总结出"让 AI 流程化"的 3 条原则

这也是我最想分享的部分：

如果不这样做，AI 主动使用 skill 的概率很低。原因不是 AI 笨，而是 agent 的执行是有"决策成本"的：

• 它要先意识到有 skill；
• 再判断该不该用；
• 再决定什么时候用。

而把基础上下文放进 AGENTS.md 或通过 hook 提前注入，本质上是在减少决策点。Vercel 的评测结果说明了这种"被动上下文"在某些场景下会更稳定。

只写一堆说明文档不够。AI 在工程任务里最需要的是：

• 一个可以直接执行的入口；
• 明确的参数；
• 稳定的返回结构。

所以我把 find-component.js 做成统一入口，并定义了固定 JSON 输出（ok / matches / noMatch / scanTriggered / hint / error 等），这会明显提升 AI 的执行稳定性。

这是最容易被忽略、也是最影响稳定性的一点。如果给 AI 暴露一堆脚本：

• resolve-scope.js；
• match-component.js；
• run-scan.js；
• scan-components.js；
• index-manager.js。

它理论上能拼起来，但实践里很容易漏步骤、顺序错、参数错。所以我在 Skill 里显式规定：

• 查找时用 find-component.js；
• 构建时用 run-scan.js；
• 更新描述时用 update-component-summary.js。

把复杂系统收敛成几个明确入口，AI 才容易稳定执行。

六、这次实践里一个很重要的认知转变

我原来以为"写 skill"是在给 AI 增加能力。现在更像是在做：给 AI 增加"默认工作方式"。换句话说，skill 不只是能力包（capability bundle），也是流程控制器（workflow controller）。

• AGENTS.md 负责"告诉 AI 世界观"；
• Hook 负责"提醒 AI 现在该用哪套流程"；
• Skill 负责"把动作做完，并且做得稳定"；
• 日志/CSV/usage 负责"让系统可观测、可迭代"。

这套思路不只适用于组件复用，后面也可以迁移到：

• 任务优化闭环；
• 日志分析标准化；
• 策略诊断流程；
• 代码规范治理。

七、这套方案当前的价值

• AI 开发前先查可复用组件，而不是直接新建；
• monorepo 下按"当前应用 + 共享组件"范围检索；
• 索引缺失自动扫描；
• 组件描述富化进入主流程；
• 匹配质量有加权与反馈回路；
• 整体流程有明确入口和输出协议。

八、结语：让 AI 少一点"即兴发挥"，多一点"工程纪律"

这次组件复用 Skill 的开发过程，对我最大的启发不是"AI 能帮我写多少代码"，而是：AI 其实非常适合被放进一套清晰流程里工作。只要把下面三件事做好：

• 基础上下文（AGENTS.md / hooks）；
• 可执行入口（工具函数）；
• 明确流程边界（统一入口 + 输出协议）。

AI 就不会只是"一个会说话的代码补全器"，而会更像一个遵守团队规范的工程协作者。而这，才是我做这个 Skill 真正想要的结果。

往期回顾

1.财务数仓 Claude AI Coding 应用实战｜得物技术

2.日志诊断 Skill：用 AI + MCP 一键解决BUG｜得物技术

3.Redis 自动化运维最佳实践｜得物技术

4.Claude在得物App数仓的深度集成与效能演进

5.Claude Code + OpenSpec 正在加速 AICoding 落地：从模型博弈到工程化的范式转移｜得物技术

文 /魏无涯

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。