今天不谈那些花里胡哨的Prompt技巧聊聊我更关心的一件事当AI编程Agent越来越能写代码我们怎么让它遵守工程纪律先说我遇到的一个真实场景。上个月我让Agent帮忙重构一个老模块它确实把功能做完了测试也能跑通但提交上来我差点当场崩溃——它顺手把格式化配置改了、在业务代码里埋了个print调试、commit message写着“update files”还改了三个跟本次需求毫无关系的文件。代码能跑但工程上完全不合格。这个问题的根源不是Agent能力不够而是它没有“纪律”。GitHub Skills系统正是用来解决这个问题的。它把团队约定、代码规范、提交流程、检查清单这些工程纪律从人的脑子里、Wiki里、Review comments里沉淀成Agent能主动读取、理解和执行的“技能包”。这篇文章我从实操角度拆解一下这套系统的设计思路、落地步骤和踩坑记录给正在用Claude Code、Codex、Copilot等工具做开发的同学一个参考。1. 为什么AI Agent越强越需要“工程纪律”这一节先把问题聊透。很多人觉得Agent写代码不守规矩是因为模型不够聪明其实恰恰相反问题出在“工程”这个词上。1.1 Agent的能力陷阱会写代码不等于会交付代码现在的编程Agent单点能力已经很强了。给它一个明确到函数级的任务它可以写出质量尚可的代码甚至能做跨文件修改。但软件开发从来不是“把代码写出来”这么简单它是一套包含约束、流程、质量门禁的复杂系统。我见过太多类似的场景Agent花十分钟写完了功能但它不会主动去检查“这个改动是否影响现有调用方”“性能有没有退化”“是否需要补充测试用例”“提交信息是否符合规范”。不是它做不到而是模型默认的目标是“完成用户的显式指令”它缺少一套“在真实团队里干活”的默认规则。这就像一个新入职的毕业生技术上可能很能打但不清楚公司的代码评审流程、发布窗口、命名约定和合入标准。这时候需要的不是更高的智商而是一本岗位手册。1.2 工程纪律的构成要素工程纪律往细了说可以拆成四层规范层命名方式、代码风格、目录结构、依赖管理规则、commit message格式。流程层需求澄清、方案设计、编码、自测、评审、合入、发布的顺序和门禁。质量层什么场景必须写单测、覆盖率底线、不允许出现的反模式、性能和安全红线。行为层如何提问、遇到歧义如何处理、发现范围蔓延如何上报。四层缺一不可。规范层管“写出来像不像这个项目的代码”流程层管“活儿按什么顺序干”质量层管“什么算干完了”行为层管“遇到意外怎么办”。1.3 为什么选择Skills机制来承载纪律有了这些纪律接下来就是怎么把它交给Agent。目前主流做法有三类第一类是写进System Prompt简单直接但会随着项目变长而稀释维护困难第二类是放在项目文档里让Agent自己去读问题是Agent不一定知道什么时候该读哪篇第三类就是Skills机制。Skills机制的核心优势是按需加载。它不是一股脑把几十条规则塞给Agent而是把纪律按场景拆成一个个独立的技能包Agent在遇到对应场景时主动调取。这个设计很像给员工发工作手册而不是把整个公司制度贴在工位上。效果完全不同。2. GitHub Skills系统是什么给Agent一本“岗位说明书”聊了一圈概念现在来看看这个系统真正的样子。我拿目前比较有代表性的实现来说明因为它的设计思路基本成为了社区的一致标准。2.1 Skills的基本工作方式一个Skill本质上是一个包含SKILL.md的独立目录。这个Markdown文件里有结构化的Frontmatter包含技能名称、描述、适用场景、允许使用的工具等元信息和正文包含具体的规则、步骤、约束和检查清单。Agent在执行任务时会根据对话内容判断是否应该加载某个Skill。加载后Skill内容会以优先级较高的上下文形式注入模型Agent会按照其中的规则来约束自己的行为。你可以把它理解为“工具说明书”。不打开工具箱时说明书不占地方一旦需要用到里面的工具说明就能立刻派上用场。2.2 一份标准Skill的结构解析SKILL.md文件的开头是YAML格式的元信息这个部分尤其重要。描述写得是否准确直接决定了Agent在什么情况下会触发它。--- name: git-workflow-compliance description: 用于强制执行Git提交规范和PR描述规范。当你准备提交代码、创建Pull Request或编写commit message时必须使用此Skill。如果你的内存中检测到git操作相关的意图也请加载本技能。 allowed-tools: - git - gh ---正文部分我习惯按照“场景识别 - 执行步骤 - 硬性约束 - 检查清单”四段式来写# Git工作流规范 ## 适用场景 - 执行git commit、创建分支、提交PR、处理合并冲突时 ## 执行步骤 1. 提交前先运行 git status 和 git diff梳理所有改动文件 2. 将改动按逻辑拆分为独立提交禁止一个提交混入多个无关改动 3. Commit message遵循Conventional Commits规范 ## 硬性约束 - 禁止修改与本任务无关的文件如果文件被意外修改使用 git checkout -- file 还原 - 禁止提交包含密钥、日志文件、临时文件的改动 ## 检查清单 - [ ] commit message是否包含类型、作用域和描述 - [ ] 是否有多余文件被误改 - [ ] 是否已在本地运行全部相关测试这样一段内容比一个小时的模型微调便宜也比在System Prompt里塞两百行规则更聚焦、更精确。2.3 Skills与“大而全”文档的区别很多团队把几十页的《开发规范V12》丢给Agent效果通常不理想。一份大文档表面上内容详尽实际用起来有几个问题一是上下文窗口消耗太大Agent读到后面忘了前面二是与当前任务相关性低的内容会分散注意力三是如果规范之间互相冲突Agent会陷入混乱。Skills机制做了两件事来规避这些问题拆细和提示。拆细就是把内容按场景、角色或工作流拆成多个技能每个技能只解决一类问题。提示则是通过精确的description让Agent在正确的时机加载。本质上这改变了Agent获取规则的粒度——从“全量加载”变成“按需加载”。3. 实操手工打造一套“工程纪律”Skills理论讲多了容易飘这一节直接给可以抄作业的完整做法。我以“给团队新建一套工程纪律Skills并跑通智能体开发流程”为例从零开始逐步演示。3.1 第一步盘点痛点确定最小纪律集不要一上来就想搭建一套覆盖所有场景的庞大技能库那是给自己挖坑。我的建议是先做减法从最近一个月里Agent犯过的错误里挑出前三类最痛的把对应的规则写成第一个Skill。比如最近Agent频繁出现的问题集中在三个方面改动范围失控、不写测试、提交信息一团糟。那第一版技能库就只覆盖这三块。每个Skill都是一页撑死了三四页的小文件超过就先砍掉一半能多精简就多精简。3.2 第二步编写四个基础Skills根据痛点第一版可以落地四个技能任务启动、代码修改、测试验收、提交协作。第一个是任务启动时的需求澄清技能。它的作用是在Agent接活之后动手之前强制它先完成需求澄清--- name: requirement-clarify description: 在任何编码任务开始前使用。当用户给了一个较模糊的开发需求、涉及多文件的改动任务、或用户没有给出明确的验收标准时必须加载本Skill进行任务澄清。 --- ## 澄清步骤 1. 用不超过30个字复述你对本次任务的理解并交给用户确认 2. 明确改动范围列出可能需要修改的文件清单 3. 明确风险点对已有代码的影响、是否涉及数据迁移、是否有兼容性要求 4. 明确验收标准用户如何判断本任务完成 ## 注意事项 - 如果用户给予了明确的“直接执行”指令可以跳过完整澄清但仍应在动手前列出你的执行计划 - 如果任务涉及多个模块必须先拆解为子任务清单第二个技能是编码阶段的范围控制--- name: scope-discipline description: 在Agent修改代码文件时使用。当执行代码生成、重构、bug修复、功能开发时用于约束修改范围防止蔓延。 --- ## 行为准则 1. 每次修改前先用 git status 检查工作区状态 2. 只修改与任务直接相关的文件禁止顺手“优化”相邻代码 3. 如果发现必须修改额外文件先记录在改动说明中向用户报告后再行动 4. 不使用全局查找替换除非明确要求第三个技能是测试纪律。第四个是Git和PR规范与上一节的示例类似。3.3 第三步定义加载时机和优先级Skill能不能起作用触发时机很关键。在description里把触发场景写具体、写强烈“必须”比“应该”有效“检测到git操作”比“提交代码”更容易被命中。同时要注意优先级问题。如果多个Skill对同一环节都有要求Agent会无所适从。一个简单的做法是建立优先级规则用户显式指令大于Skill高优先级Skill大于低优先级SkillSafety类Skill永远最高。3.4 第四步用一组Skills覆盖完整交付链路四个基础技能都搞定后你实际上就有了一个覆盖完整交付链路的技能组需求进来要求澄清。动手之前有范围控制。写完代码有测试验收。提交协作有Git规范。遇到拿不准的事有升级机制。最初这套组能覆盖八成场景就够了剩下的可以在实际使用中逐步补充。一次只加一个节奏感很重要。4. 核心环节解析纪律如何真正被Agent执行Skill文件本身只是一堆文本真正让它产生约束力的是背后的执行机制。我在带着团队落地这套方案时摸索出几个关键策略。4.1 从“建议”到“强制”优化语言设计这是最容易犯的误区。早期我们写Skill时语气太温和大量使用“建议”“可以考虑”“尽量”这类软性词汇结果Agent执行时基本当成耳边风。后来我调整了措辞体系规则从“should”升级为“必须/禁止/强制”。经验是明确的使用“必须”禁止事项以“禁止”开头无条件要求直接列清单。语气强硬但目标清晰Agent的遵守度会有肉眼可见的提升。4.2 把抽象规范变成可检查项“写出清晰的代码”是句废话Agent无法执行“函数长度控制在50行以内”“禁止超过三层嵌套”才是可检查项。我在每一个Skill里都加了一个“自检清单”让Agent在完成任务或提交前逐项自查。把检查动作嵌入流程里等于给Agent加了一个质量门禁。4.3 教会Agent说“不”和“上报”比较反直觉的一点是工程纪律不只是让Agent听话也包含“不听话”。所谓不听话是指当用户指令和规则冲突时的正确反应。我在技能里专门设计了一个上报机制。如果用户要求做的事违反硬性约束比如要求把密钥硬编码进代码、跳过测试直接提交、删除未备份的数据Agent必须停止操作并向用户说明原因而不是闷头执行。这一步很关键。因为让Agent遵守规则的最终目的不是把它驯化成盲目的执行器。它有判断力才有资格作为工程团队的协作成员存在。4.4 Skill也要有版本和迭代节奏代码要维护Skill文档同样要维护。我见过很多团队的Skill文件墙技能库里躺着十几条旧规则早已不合时宜。这里给出一个简单的迭代节奏每次Code Review、每次事故复盘、每次Agent出现重复错误都是更新对应Skill的时机。让Skills和团队的认知同步进化它才不会变成坏规矩。5. 落地的坑与排查技巧实录使用Skills一段时间后我总结了一份常见问题手册。真正常踩的坑其实就那么几个。5.1 Agent不读Skills怎么办这是最常见的问题。明明把Skill文件放在正确位置了Agent就是不触发。先检查description写没写清楚。如果描述里写的是“Git规范”触发率一定低。我把描述改成“当你检测到commit、PR、merge等Git行为时必须优先加载此技能”命中率立刻提升。再检查Skill是否在Agent能读到的目录里。全局Skills目录和项目Skills目录是分开的如果Rule放在全局但项目有同名限制Agent可能读不到。最后是触发条件冲突。检查是否有其他更高优先级的指令或系统提示词覆盖了Skill的内容。5.2 Skills之间的规则冲突当技能库扩大到一定规模后不可避免会出现两条规则“打架”。比如提交规范技能里禁止“修复拼写和格式问题时混入功能改动”但代码规范技能要求“发现明显语法错误应立即修复”。这时候Agent会陷入两难。解决方法是给每个Skill增加一个conflict-resolution提示明确在冲突时如何取舍。还可以把类似主题的Skill进行合并在物理上消灭冲突源头。5.3 Skill内容被“遗忘”上下文长度问题有时Skill加载了但Agent干着干着忘了里面的要求。这取决于Agent对长上下文的关注衰减。规避方法Skill里最重要的3条硬性约束要放在文件最靠前的位置并且用全大写或加粗突出要求Agent在执行关键动作前回顾一下Skill内容把最关键的检查清单压缩到指令末尾重复一遍。5.4 Skill写得太空说了等于没说我自己也写过不少“看似专业实际无用”的Skill。比如我一开始写过“开发前先进行需求分析明确技术方案”但没写清楚怎么分析。后来改成了具体的步骤和问题列表列出待确认的3个问题给出每个问题的最小可选方案等用户选择后再动手。效果立刻不一样。## 不可执行的无效版本 开发前先进行需求分析并制定技术方案。 ## 可执行的改进版本 开发前输出以下3项 1. 本次任务核心问题的复述不超过30字 2. 3个待确认问题每个问题给出A/B两个备选方案 3. 你推荐哪个方案及原因技术栈的差异会让Skill看起来五花八门但凡是执行效果好的Skill几乎都具备同一个特点Agent读了以后清楚地知道自己下一步该输出什么、不该做什么。这比文采更重要。5.5 常见问题速查表现象优先排查方向调整建议Skill完全不触发description写得模糊强化触发词注明“必须”和场景Skill内容被无视规则太多或语气太软精简条数用“必须/禁止”重写多个Skill互相打架规则存在重叠冲突合并同类项设置优先级Agent“做得过分”硬性约束太少增加“禁止改动无关文件”等红线忘记后续流程缺少过程提醒机制要求Agent在关键节点自检并回显6. 影响范围一个Skill如何盘活整个开发流程最后聊聊可以把这个系统用到什么程度。6.1 个人开发者给AI打工的自己装个刹车独立开发者往往是Skills系统最大的受益者。因为没有团队评审环节做第二道防线Agent踩坑会直接变成线上事故。我用这个方式管理Agent之后至少不再出现“为了改个样式把构建配置弄坏了”的情况。这就像F1赛车的HANS系统平时可能用不上但关键时刻能保住你的头部——也就是你的代码库健康度。6.2 团队协作把Code Review规则前置传统工作流里Code Review是人在看规则靠评审者把关。现在可以把大量已知规则前置到Skill里让Agent在写代码的时候就绕开。团队的编码规范从“Review的时候被人挑出来”变成了“写之前已经被避开”。Code Review的时间就能更多地花在逻辑审查和方案把关这些机器替代不了的事情上整个团队的迭代速度都会有明显改善。6.3 开源项目让贡献者Agent“入乡随俗”现在越来越多的开源项目开始使用自动化Agent来提交PR。如果每个Agent都按自己的风格来项目维护者会疯掉。有了Skills项目维护者可以把贡献指南、代码风格、CI要求、提交规范打包成一套标准技能包。任何Agent来做贡献先加载这套技能输出的PR风格就会相对统一。这就等于建立了项目自己的“工程文化”。6.4 平台工程与未来想象从更长远的视角看将Skill看作“组织的操作手册”可能比“工具说明”更合适。一个成熟的研发组织未来会沉淀大量技能。让新人在Agent的辅助下通过按需加载的组织经验快速理解“这个团队如何工作”“哪些红线不能碰”——这样做能显著降低新成员的上手成本。关于这个系统我的一点经验这套东西我实际跑了几个月最大的感受是管理Agent的工程纪律本质上是在管理人对“什么叫做好代码”的共识。技能本身反而是最不难的部分难的是你想让Agent遵守哪些规则、为什么要遵守这些规则、哪些红线在你这个团队里绝对不可以踩。把这些问题想明白技能库自然就长出来了。最后分享一个实用的小技巧不要等到需要用了才想起写Skill。每次Agent犯下让你眉头一皱的低级错误立刻花十分钟把它变成一条新的技能规约。持续两周左右你的技能库就会开始真正贴合自己的团队风格。这个系统最让人上头的点在于规则一旦沉淀下来价值积累会一次次发生在同一个地方。而你的Agent也会在一次次的遵守纪律中从一个只会写代码的工具变成真正懂协作的搭档。