浅谈 SKILL 研发的最佳实践——以百补详情助手为例

本文以百亿补贴详情助手 Skill 的迭代历程为例,总结 Skill 研发与迭代实践。文章先梳理业界方法论——Claude Skills 的渐进式披露与控制调优、MiniMax 的工业化规范、以及常见的 Skill 设计模式;随后从架构设计、研发效能、运行优化 3 个维度展开详细介绍了桥接器解耦本地 Skill 与远程 Agent、按需共享上下文、优先输出优质 HTML 报告等高效实践,帮助读者提高 Skill 研发效能。


背景


自从 Skill 概念被 Anthropic 提出,我所在的团队已开发 50+ Skill,涵盖补贴查询/创建/分析、舆情分析、频道巡检、智能圈品、素材生成、代码助手、商品诊断等场景。这一路做下来,我们也读了大量讲 Skill 最佳实践的文章和仓库,比如 Claude Skills 官方文档[1]、MiniMax 开源仓库[2]、Agent Skills 开放标准[3],慢慢发现一个共同点:对怎么写好SKILL.md的标准讲得多,但对 Skill 如何研发、如何迭代的具体实践介绍得相对少。

和内部运营、产品、研发小二聊得越多,我们越确信一件事:不能持续迭代的 Skill,说到底只是一次性的 demo。所以本文换个角度,从"架构设计、研发效能、运行优化、呈现方式"四个维度切入,以 bybt-detail-assistant(百亿补贴详情助手,50+ commit)的实际研发历程为例,介绍我们在迭代开发 Skill 过程中攒下的经验,给读者一些简单、能直接上手的 Skill 开发实践。


百亿补贴详情助手简介


bybt-detail-assistant(百亿补贴详情助手)是百亿补贴商品详情页的智能分析 Skill,由本地 Skill 文件和远程 Agent 两部分组成,两者之间通过 xiaomi.py 桥接脚本连接:


bybt-detail-assistant 的架构示意图


本地 Skill 的核心设计是"决策树路由 + 远程 Agent API 桥接"——本地负责信息收集、商品查询和结果呈现,而日志搜索、截屏分析这类依赖集团内部在线服务和知识库的深度分析,则交给远程 Agent。



业界 Skill 最佳实践梳理


▐  3.1 Claude Skills:渐进式披露 + 控制调优


Anthropic 的官方最佳实践[1]和 Agent Skills 开放标准[3]建立了 Skill 设计的核心框架。社区对其做过 14 种设计模式的深度拆解[4],其中以下几个关键理念对我们影响最大。


渐进式披露(Progressive Disclosure)[1][4]:

一般来说,Skill 的加载分三层:

  • L1 元信息(name + description)  → 每次会话启动时加载,决定 Skill 是否被激活;

  • L2 SKILL.md 正文 → 判断需要使用时才加载,是 Skill 的主指令集;

  • L3 附件资源(references/、scripts/)→ 执行过程中按需读取,不占用 L2 的 token 预算。

官方建议 SKILL.md 正文控制在 500 行以内,超过则拆分为独立文件[1]。其中,description 字段尤为关键,它不只是摘要,更是 Agent 在选择 Skill 时的重要信号。官方建议 description 要写得"有侵略性"(pushy),明确列出触发条件和排除条件,bybt-detail-assistant 的 description 覆盖了"截图/链接/ID/traceId/找日志"等多种触发词。


控制调优(Control Tuning)[1][4]:

核心原则是让指令自由度与任务鲁棒性相匹配,Anthropic 官方文档中这一概念叫 matching instruction freedom to task fragility,文章[4]中称为 Control Tuning pattern,部分中文文章译为"自由度匹配"。



▐  3.2 MiniMax Skills:标准化仓库 + 工业化生产


MiniMax 的开源仓库[2]是目前社区中成熟的 Skill 工业化样板(16+ 生产级 Skill,含 frontend-dev、fullstack-dev、android-native-dev 等),其工程化体系值得借鉴:



另外,MiniMax 的 CONTRIBUTING.md 还要求"One PR, one purpose":每个 PR 只做一件事(新增/修复/改进 Skill),这和我们 §4.2.3 的小步提交思路正好一致。


▐  3.3 Skill 设计模式梳理


Skill 的设计模式是一个常被忽视但极有价值的维度。在对社区一批生产级 Skill 逐行分析的基础上,我们把它们归为两类:一类是决定 Skill 整体骨架的工作流结构模式,另一类是贯穿SKILL.md 编写全过程的高频实践模式[4]。

先看 6 种核心的工作流结构模式:



bybt-detail-assistant 实际是模式 2(决策树)为主干,路径内部混合模式 1(线性)和模式 3(循环迭代) 的复合结构。认清自己的 Skill 适合哪种模式,是结构设计的第一步,可以参考下图来选择。


Skill 工作流模式的决策树示意图


选择建议:如果你的 Skill 有"输入类型多样 → 处理逻辑互斥"的特征,优先考虑模式 2(决策树);如果有"尝试 → 验证 → 重试"的特征,混入模式 3(循环迭代)。两者组合是诊断类 Skill 的常见范式。

在工作流骨架之外,还有几种贯穿 SKILL.md 编写的高频实践模式[4],同样值得关注:



有了上述业界方法论作为参考,接下来我们回到 bybt-detail-assistant 自身的迭代历程,逐一展开在架构设计、研发效能、运行优化和呈现方式四个维度中的具体做法。


bybt-detail-assistant
技能研发最佳实践


▐  4.1 架构设计


  • 桥接器:解耦本地与远程的迭代


问题背景:bybt-detail-assistant 目前处在边试用边迭代的阶段,需要频繁升级(新增埋点字段解读、优化匹配算法)。如果把所有逻辑都放在本地 Skill,每次升级都要改动 SKILL.md 并重新发版,用户还得跟着频繁更新本地版本,很难保证所有用户体验一致。

我们的解法是:桥接器 xiaomi.py 本质是调用 Agent API(复用了原“百补详情小蜜 Agent”)客户端脚本。由于我们设计了稳定的协议,远程 Agent 升级时(如支持新埋点字段解读),Skill 作者无需修改本地 Skill。这就实现了"远程能力迭代"与"本地 Skill 版本"的解耦。


本地 Skill文件 与远程 Agent 版本解耦示意图


这套分离架构,说到底是在稳定性与迭代速度之间做的一次主动取舍,值得展开讲讲。

就缺点而言,最显而易见的代价就是跨系统桥接天然比单体更“脆”:本地与远程通过 xiaomi.py约定的接口通信,多出一段网络链路和一层协议契约,任意一端的问题都可能让端到端链路失败;排查问题时也要在两个运行环境之间来回定位,归因成本更高。

但我们还是进行了拆分,根本原因很简单:这两部分的 变化节奏 和 迭代成本 完全不同。远程 Agent 扛的是分析能力,比如埋点解读、问题排查,几乎每周都在跟着新增的埋点和排查场景往上加。这类逻辑要是塞在本地,既慢,又容易版本不一致,还没有灰度的余地。放在远程 Agent 就不一样:版本管理、灰度发布、可观测、一键回滚都很成熟,天生适合安全又快速地上线。想试新逻辑,先灰度一小撮流量;出了问题,一键回滚,用户完全无感,也不用天天升级本地。本地 Skill 只保留信息收集、商品查询、结果呈现这层「薄客户端」,改动少,本就该是整条链路里最稳的一环。

就是基于上面的考虑,我们用 架构边界 把 需要保持稳定 和 需要高频迭代 两类诉求在物理上隔开,在远程分析能力还在高频迭代的当下,这道隔离带来的收益,远大于桥接本身的脆弱性。


  • 决策树:按需加载而非全量展开


问题背景:我们的 SKILL.md曾经把各个功能的描述交织在一起,在低端模型上经常让 Agent 顾此失彼、迷失方向。因此,我们把 SKILL.md划分为三条逻辑互斥的路径(例如执行路径 A(输出详情访问报告)时,完全不需要知道路径 C(找详情访问日志)的细节),Agent 的执行效率明显提升。

我们的解法是:在共享全局约束的情况下,使用决策树拆分路径,每条路径自包含输出规则和主动引导逻辑。


全局约束(所有路径共用,~60行)  ↓决策树(4条规则,~20行)  ├─ 路径A:traceId 分析(~30行)——线性模式  ├─ 路径B:商品查询(~15行)——线性模式  └─ 路径C:截图+日志(~250行)——循环迭代模式


这是模式 2(决策树+按需加载)在单文件内的实现——通过层级标题实现逻辑隔离。这种基于执行路径隔离的实践还有一个好处是便于后续拆分:目前百补详情助手的 SKILL.…

— 以上为试看内容(约 40%),开通会员后阅读全文 —