让AI流程化组件复用Skill开发让AI成工程协作者以下是正文做这个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放基础上下文常驻把组件复用优先的规则、组件索引入口、扫描后需要做的事情放进AGENTS.md或同类常驻上下文机制里。目的不是塞满文档而是让AI每轮都知道这个仓库有组件复用机制默认应该先查可复用组件查不到再考虑新建扫描后还有描述补全流程需要继续执行。这层解决的是AI根本不知道有这套机制。不写进去AI主动使用skill的概率确实会很低这点踩过坑。Hook做路由增强提高触发概率如果运行环境支持hooks例如Claude Code的UserPromptSubmit支持在用户prompt处理前注入额外上下文就可以做一层意图路由增强在用户提到组件复用 / 是否有现成组件 / 封装组件 / 查组件等语义时给AI注入提示让它优先走组件复用流程。Claude的文档明确写了UserPromptSubmit会在处理前触发并且可通过additionalContext注入上下文。这层解决的是AI知道有skill但不一定想起来用。Skill提供流程和工具真正执行Skill不是只写说明文档而是要提供明确的调用入口稳定的输出格式可执行脚本失败时的兜底逻辑。OpenAI的Codex Skills文档里提到skills是渐进披露机制运行时先看到skill的元信息尤其是description只有决定使用时才加载完整SKILL.md而且隐式触发高度依赖description。这也是为什么skill的触发边界和描述要写得非常清楚。这层解决的是AI想用了但执行过程不稳定。这套Skill在源码里是怎么落地的实现下面是这次组件复用Skill的几个关键实现点先把入口收敛成一个find - component.js在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 - scopeupdateIndex自动触发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必须完成这一步。这其实就是流程化思考的精髓不是建议而是纳入主流程。让Skill不只是搜索器还是反馈回路一个很容易被忽视的点是查找命中后还记录了使用行为usage - tracker。这意味着系统不是静态的它会逐步学习团队偏好哪些组件经常被复用哪些组件在某个app里更常出现哪些结果应该在排序中更靠前。这是一种很轻量但非常实用的反馈机制——不需要搞复杂训练也能提升AI下一次推荐质量。这次实现里总结出让AI流程化的3条原则这也是最想分享的部分原则1把基础上下文放进AGENTS.md或用Hook注入如果不这样做AI主动使用skill的概率很低。原因不是AI笨而是agent的执行是有决策成本的它要先意识到有skill再判断该不该用再决定什么时候用。而把基础上下文放进AGENTS.md或通过hook提前注入本质上是在减少决策点。Vercel的评测结果说明了这种被动上下文在某些场景下会更稳定。原则2Skill需要直接提供工具函数给AI调只写一堆说明文档不够。AI在工程任务里最需要的是一个可以直接执行的入口明确的参数稳定的返回结构。所以把find - component.js做成统一入口并定义了固定JSON输出ok / matches / noMatch / scanTriggered / hint / error等这会明显提升AI的执行稳定性。原则3显式告诉AI调哪些函数并把分散逻辑聚合到一个入口这是最容易被忽略、也是最影响稳定性的一点。如果给AI暴露一堆脚本resolve - scope.jsmatch - component.jsrun - scan.jsscan - components.jsindex - 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真正想要的结果。