企业官网建设流程全解析

今天不谈那些花里胡哨的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大于低优先级Skill，Safety类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 常见问题速查表

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，也会在一次次的遵守纪律中，从一个只会写代码的工具，变成真正懂协作的搭档。