OPEN SOURCE DEEP DIVE
Agent Skills:编码智能体的全流程工程规范
Addy Osmani 将编码智能体的开发流程封装为可执行技能,覆盖规格、规划、增量实现、测试驱动、审查与发布,强调证据化验证和渐进式落地。
项目定位:把工程判断变成可执行流程
agent-skills 不是一个提示词合集,也不是让编码代理一次完成整项工作的自动化框架。它把资深工程师反复使用的开发习惯拆成一组可发现、可调用、可验收的流程文件,让代理在规格、规划、实现、测试、审查和发布各阶段按同一套证据要求行动。本次精读对应仓库 0.6.16 标签,核心内容是 25 个技能、9 个生命周期命令、4 个专业角色和 7 份共享检查表。
这组资产的出发点很明确:编码代理经常能生成看起来正确的代码,却会跳过需求澄清、测试失败复现、边界条件、回归验证和发布风险检查。项目没有试图用一份超长总提示词解决所有问题,而是把职责切开,让代理只在当前任务需要时加载对应流程。这样既减少上下文浪费,也把“做完”从一句主观判断变成一组可以回读的产物和命令结果。
仓库面向多个宿主环境提供安装说明,包括 Claude Code、Codex、Cursor、Gemini CLI、Copilot、OpenCode 等。不同宿主对命令、插件和技能路由的支持并不完全相同,因此项目把通用流程放在技能文件中,把命令适配和安装方式留在各宿主的接入文档里。这个边界判断很重要:技能描述的是工作方法,命令只是把多个方法编排成一条可调用的入口。
生命周期与仓库结构
项目用六段生命周期组织主要工作:定义、规划、构建、验证、审查和发布。与之对应的 9 个命令是 /spec、/plan、/build、/test、/constraints、/review、/webperf、/code-simplify 和 /ship。命令不是独立的知识来源,而是把规格、任务拆解、增量实现、测试驱动、审查和发布等技能组合起来。
| 阶段 | 主要问题 | 代表性技能 |
|---|---|---|
| 定义 | 究竟要解决什么问题,哪些边界不能越过 | interview-me、spec-driven-development、constraint-driven-development |
| 规划 | 如何拆成可独立验收的小任务 | planning-and-task-breakdown |
| 构建 | 怎样用薄切片持续交付可工作的系统 | incremental-implementation、test-driven-development |
| 验证 | 如何用可重复证据证明行为正确 | browser-testing-with-devtools、debugging-and-error-recovery |
| 审查 | 正确性、可读性、架构、安全和性能是否达标 | code-review-and-quality、security-and-hardening |
| 发布 | 部署、观测和回滚是否准备好 | shipping-and-launch、observability-and-instrumentation |
仓库把技能、角色和命令视为三个组合层。技能提供过程,角色提供不同审查视角,命令负责按阶段编排。负责代码审查、安全审计、测试工程和 Web 性能的专业角色不是额外人格装饰,而是在发布前从不同方向检查同一份改动。共享检查表则把测试、安全、性能、可访问性、可观测性和完成定义等跨技能材料集中维护,避免每份技能各抄一份后逐渐漂移。
仓库还提供一个名为 using-agent-skills 的元技能,用于判断当前任务应当进入哪条流程。它的使用方式取决于宿主能力:如果宿主已经能根据描述自动路由,就不应把元技能作为永久上下文重复加载;如果宿主没有原生路由,才让它承担入口职责。项目明确反对一次加载全部技能,因为这会稀释真正相关的流程,也会让代理在手头任务上失去重点。
技能结构与渐进披露
每份技能的核心是带 YAML 前置元数据的 SKILL.md。名称必须使用小写连字符格式,并与目录名一致;描述必须同时说明“提供什么”和“何时使用”。描述不是流程摘要,因为代理通常会先看到名称和描述,再决定是否读取正文。若描述提前塞入完整步骤,代理可能只按摘要执行,反而错过正文中的约束和验收条件。
推荐结构包括概述、适用条件、核心流程、常见合理化借口、危险信号和验证清单。最常见的段落不是原则罗列,而是“代理可能会说”的反驳表:例如“代码太简单,不需要测试”“先把功能做完再补规格”“测试只是偶发失败”。表格把借口和事实放在一起,使流程在时间压力、沉没成本或权威压力下仍然可执行。验证段则要求每个完成条件都能由测试输出、构建结果、截图或文件差异证明。
项目采用渐进披露控制上下文成本。主技能建议保持在 500 行以内,较长检查表放到共享目录,脚本优先于大段内联代码。代理启动时只加载技能名称和描述;真正进入工作后,才读取对应正文和按需引用的材料。这个设计把“知道何时使用”与“完整读完流程”分开,也要求作者把高频、短小、会改变行为的规则留在主文件中。
编写原则强调过程而非知识、具体命令而非抽象要求、证据而非假设,以及模型中立。项目明确反对把某个模型曾经犯过的错误固化成所有模型都必须执行的机械步骤。一个步骤如果离开某个模型名就无法解释,应该进入问题记录,而不是塞进通用技能。这一判断直接来自跨模型迁移研究的风险:针对弱模型工作方式编写的流程,可能让更强的模型表现反而下降。
执行模型:薄切片、测试先行与停止条件
构建阶段以增量实现和测试驱动为主。一个变更要尽量切成薄纵向切片,每一片都能独立编译、测试和提交,并让系统在片与片之间保持可用。测试驱动流程使用红灯、绿灯、重构三步:先写能暴露当前缺口的失败测试,再写最小实现让测试通过,最后在不改变行为的前提下整理代码。缺陷修复还要求先稳定复现问题,形成可重复的失败证据,再进入修复。
/build auto 是最容易被误解的部分。它会根据已经批准的计划连续完成多个任务,减少人工逐步确认的次数,但不会取消验证。每个任务仍然需要测试驱动、独立验证和独立提交;遇到歧义、失败、高风险操作或计划外发现时,流程必须停下。这里改变的是任务之间的人工停顿,不是质量门槛。
执行过程中,代理需要维护一组明确的停止条件。测试无法稳定复现、要求与规格冲突、改动会越过已声明边界、需要不可逆的数据操作、或者验证环境不可用时,继续生成代码没有价值。项目的流程把这些情况视为回到定义或规划阶段的信号,而不是用更多代码掩盖不确定性。
另一个关键约束是保留验证证据。仅说“已经测试”不算完成,必须记录实际运行的测试命令、结果、受影响范围以及必要的浏览器或接口检查。提交应保持原子性,通常以约 100 行的变更作为可审查尺度;较大的改动要拆分为有意义的步骤,让失败时可以定位、回滚和二分查找。
定义与规划:先消除错误问题
定义阶段并不总是从写规格开始。需求含糊时,interview-me 会一次只问一个问题,通过连续澄清逼近真实目标,而不是一次抛出很长的问卷。它关注用户真正想改变的结果、现有替代方案、必须保留的约束和可接受的失败方式。若问题已经足够清楚,代理应直接进入规格,而不是为了走流程制造访谈。
规格驱动的技能要求在编码前写清目标、范围、命令、目录结构、代码风格、测试策略和边界。规格不是替代码做设计,而是给后续任务提供可验证的语义。边界部分尤其重要,因为它明确代理不能碰哪些遗留模块、不能修改哪些公共接口,以及哪些行为即使看起来奇怪也必须保留。
约束驱动的技能把质量门槛前置。代理需要与用户确认检查项、阈值和执行成本,把静态检查、单元测试、集成测试、人工审查等放在合适阶段。它的核心目标不是制造更多门禁,而是防止代理为了让结果变绿而关掉检查、删除测试或降低阈值。质量规则一旦写下,就应在后续任务中稳定执行。
规划技能把规格拆成具有依赖关系的小任务,每个任务包含输入、输出、验收标准和验证方式。好的任务不是“实现后端”或“完成前端”,而是能独立观察结果的行为切片。依赖顺序也要明确,因为并行执行准备不足的任务通常只会制造更多冲突。规划产物会随着实现进展更新,是跨会话交接的事实来源,而不是一次性文档。
构建阶段的知识约束
上下文工程负责回答代理在每个时点应该看到什么。项目规则文件应记录真实使用的构建命令、测试命令、目录职责、公共边界和已知风险区,而不是复制一份理想化架构说明。任务切换时,代理需要丢弃无关历史、重新加载当前模块的约束,并在输出质量下降时检查是否加载了错误或过时的上下文。
来源驱动开发针对框架和库的“凭记忆编码”。代理先确认项目使用的确切版本,再定向获取官方文档,记录完整来源地址,并把抓取到的网页内容视为不可信数据,而不是可执行指令。若文档版本与当前依赖不一致,代理必须明确指出冲突,不能悄悄采用另一个版本的接口。这个流程特别适合快速变化的框架、新的模型接口和容易产生幻觉的配置项。
怀疑驱动开发则用于高代价决策。流程用“提出主张、抽取证据、主动质疑、重新核对、停止判断”的循环检查代理对系统的理解,必要时使用新的上下文或经用户授权的跨模型复核。它并不要求每个小改动都进入对抗审查,而是在生产风险、安全边界、不可逆操作或陌生代码中提高证据标准。
接口设计技能把公共契约当作长期负债。它强调海勒姆定律:只要调用方能观察到某种行为,就会有人依赖它,即使文档从未承诺。版本规则、边界输入校验、一致错误语义和原子幂等性必须在接口发布前决定。前端、安全和调试技能也不是代码生成后的补丁,而是在实现阶段就提供可访问性、威胁模型、故障定位和最小修复的约束。
验证、审查与发布
验证阶段要求把“应该能工作”换成可观察证据。浏览器相关任务使用运行时工具检查页面结构、控制台、网络请求和性能轨迹,而不是只看静态代码。调试流程固定为复现、定位、缩小范围、修复、补回归保护和端到端确认。每一个缺陷都应留下能在未来阻止同类问题再次出现的测试。
代码审查从五个方向检查改动:正确性、可读性、架构、安全性和性能。发现项按严重程度标注,使阻塞合并的问题与个人偏好分开。审查还关注变更大小和拆分策略,因为难以理解的巨型补丁会显著降低审查质量。简化技能使用“切斯特顿围栏”原则,要求先理解代码为何存在,再决定是否删除;行为必须保持不变,并有测试证明等价。
发布前的 /ship 是项目中最明确的并行编排之一。代码审查、安全审计和测试工程角色可以同时从各自角度检查同一份变更,再由主流程汇总阻塞项。发布技能还要求确认部署步骤、观测指标、回滚方式、功能开关和上线后的验证计划。它能压缩检查时间,但不能用并行执行替代每个检查本身的证据。
审查阶段与发布阶段之间不是简单串联。若安全审计暴露出新的公共边界,或者性能检查要求改变接口,工作应回到规格或规划层重新确认,而不是把问题降级成发布后的待办。项目的整体思路是让每个阶段产出下一阶段可以验证的输入,并在证据不足时允许流程回退。
新项目与存量代码库的两条落地路径
全新项目可以从第一天使用完整生命周期,因为还没有需要保护的历史行为。项目建议先安装技能、写好真实项目规则,再从第一个真实功能开始执行规格、规划、构建、审查和发布。测试驱动、提交纪律、安全边界和架构决策记录应被视为常驻习惯,而不是项目成熟后再补的装修工程。随着公共接口、界面、持续集成、生产部署和性能要求出现,再逐项加载对应技能。
存量代码库不能照搬这条路径。这里最大的风险通常不是做错新功能,而是改动了一段没人完整理解、缺少测试却又支撑关键业务的旧行为。因此落地顺序从只读能力开始:先写真实上下文,再用代码审查处理外部改动,用调试流程保护正在修复的问题,用怀疑驱动流程检查代理对遗留系统的断言。
第二阶段是在准备修改的区域建立安全网。并不要求为了覆盖率数字给全仓库补测试,而是对即将触碰的行为写特征测试,先固定当前结果,无论它在业务上是否理想。完成这层保护后,才适合对最混乱的热点做行为保持的简化,并用小而原子的提交降低定位成本。第三阶段让新功能重新走完整生命周期,旧代码继续使用较慢的验证优先路径,形成双速落地。
最后才处理迁移、观测和性能债务。废弃与迁移技能把旧代码视为需要持续偿还的负债,区分强制废弃和建议废弃,避免无休止地包一层再包一层。可观测性优先补在真实事故最多的路径上,性能优化则必须先测量再改,防止把时间花在从来不是瓶颈的代码上。两条路径最终会在同一稳态汇合,但存量项目需要先获得改变旧系统的安全网。
评估方法与可信边界
仓库把技能评估分成三层。结构层检查前置元数据、命名、必需段落、目录布局、引用链接、命令一致性和版本信息,成本低,适合持续集成。触发与路由层用真实用户说法测试目标技能是否排在前列,同时检查相邻技能是否被误触发,以及两个技能描述是否过度相似。行为层让代理在隔离仓库中实际执行任务,再由评分器依据预期行为检查完整轨迹。
第二层被明确描述为词法近似,而不是语义判断。它用描述与提示词的词面相似度发现问题,主要能抓住“缺少用户常用词汇”和“描述过宽”两类路由故障,无法证明代理真正理解技能。行为层更接近真实效果,但会消耗模型调用,且结果受模型、命令行工具版本、权限模式和运行次数影响。
评估文档保留了具体的日期、模型和失败案例,这一点比单一百分比更有价值。例如同一段触发描述在不同命令行版本下可能产生完全不同的命中率,同一个技能可能在文本对话中通过描述路由,却在执行环境中没有先写失败测试。项目因此要求报告结果时固定模型和工具版本,并把波动较大的数字视为样本,而不是稳定性能承诺。
当前设计也存在需要正视的边界。单独安装某个技能时,仓库根目录的共享检查表不会被一起复制,相关引用可能失效,仓库用问题编号跟踪这一可移植性缺口。9 个命令在不同宿主中并非都能以相同形式出现,有些宿主只能直接调用底层技能。行为评估依赖特定宿主和模型,不能直接外推到所有编码代理。理解这些边界之后,读者才能把项目当作可演进的工作流库,而不是一套跨平台、跨模型都保证同结果的万能规范。
适合谁,以及如何判断是否值得采用
这个仓库最适合已经让编码代理参与真实项目、但经常遇到三类问题的团队:代理直接写代码却误解需求;功能完成了却没有可重复验证;面对存量系统时改动范围失控。它也为技能作者提供了一套结构参考:如何写触发器、如何把流程拆成证据门槛、如何用反合理化表保持纪律,以及如何用结构、路由和行为三层评估检查效果。
如果团队只需要偶尔生成一次性代码,完整生命周期可能显得过重;如果项目没有可运行的测试、构建或浏览器验证环境,技能本身也无法凭空制造证据。采用时应先从一两个高价值阶段开始,记录实际节省的返工和发现的问题,再逐步扩大。判断标准不是代理是否“看起来更专业”,而是规格是否更清楚、失败是否更早暴露、审查是否能定位关键风险,以及每次发布是否更容易回滚和验证。