企业官网建设流程全解析

你有没有遇到过这种情况：同一个Agent，昨天刚教会它整理项目更新日志，今天换个新对话，它又像失忆一样从零开始摸索。工具给了、提示词写了，甚至把处理步骤直接贴进系统提示里了，可换个场景、换个项目，一切又要重来。这暴露了一个很本质的问题——我们一直在用"对话"的方式教一个长期工作的智能体做事，却忘了给它一套可以沉淀、复用、进化的能力体系。agent-skills 这个概念最近在圈子里讨论得很热，核心思路其实不复杂：把Agent能稳定执行的那部分能力，从对话上下文里抽离出来，固化成结构化的技能文件，让Agent按需加载、按流程执行。用我的话说，就是别再每次让Agent"临时发挥"，而是给它一本随时能翻的"操作手册"。

这篇文章我会结合自己维护智能体技能库的实际经历，从为什么需要技能体系、技能文件怎么组织、手写一个技能的全流程，到版本管理、踩坑记录、评估迭代，一步步拆开来讲。无论你是刚开始接触Agent开发，还是已经把它丢进了生产环境，这里面的思路和实践细节应该都能直接借鉴。

1. 为什么Agent需要一套独立的技能体系 —— 从重复调用到能力沉淀

1.1 同样的事，Agent每次都要重新摸索

说个真实场景。我维护着一个开源仓库，每天都会收到新的issue，我习惯让Agent帮我整理当天的issue，按类型归类、标出优先级、生成一份简报。第一次用的时候，我写了一大段提示词，告诉它什么样的算bug、什么样的算需求、优先级怎么判断、输出格式长什么样。效果不错，于是我把这段提示词保存下来，下次直接粘过去。

问题随之而来：这段提示词越写越长，因为我不断发现新的边界情况。今天发现"需要复现步骤的bug要标为高优先级"，明天又发现"带附件图片的issue比纯文字的更紧急"。提示词太长之后，Agent开始"消化不良"——有时候漏掉某个规则，有时候输出格式直接飘了。

更深层的问题是，这套规则只有我自己知道。团队里另一位同事想让Agent帮他做同样的事，他得重新写一遍。新同事加入，得先读一遍我那十几个版本的提示词。等到项目迭代到第三个版本时，规则文件已经和提示词混在一起，谁也分不清哪个是Agent的行为指令，哪个是项目的业务逻辑。我意识到，问题的根源不是提示词写得不够好，而是缺少一个结构化的载体来承接这些"逐渐固化的能力"。

1.2 技能与工具、插件的本质区别

很多人的第一反应是：给Agent配工具不就行了？给它一个"整理issue"的函数，它直接调用。

但工具解决的问题是"某一步怎么做"，比如"调GitHub API拉取issue列表"、"解析markdown表格"。它是一段确定的、可执行的代码。而"整理当天的issue"这件事，天然包含多个步骤：拉取数据、分类判断、优先级评估、格式化成简报、写入指定位置。每一步都需要单独决策，有些决策还得依赖上一步的输出。如果把这整件事塞进一个函数里，这个函数会变得极其笨重；如果拆成多个函数，Agent又需要知道"什么时候该调用哪个"，这个编排逻辑又回到了提示词里。

插件的思路更接近"扩展能力包"，但插件通常面向的是平台功能的扩展，比如给IDE加一个语法高亮、给浏览器加一个截图快捷键。插件有明确的入口和出口，而Agent的技能是一段有弹性的流程：入口是用户意图的识别，出口是任务目标的达成，中间步骤可以根据实际情况动态调整。

agent-skills 的思路是第三条路：把一个复杂任务定义成一个技能，技能内部是一份结构化的说明文档加若干可选的执行动作。Agent识别到这个技能适用时，把它当作一套"操作规范"加载进来，按步骤执行。这套规范既替代了冗长的提示词，又不像写死的代码那样毫无弹性。

1.3 技能要解决的三个核心问题

第一，一致性。同一类任务，无论谁来触发、什么时间触发，执行标准都应该是同一套。技能把标准固化下来，而不是依赖某一次提示词写得好不好。

第二，可维护性。规则变了，只改技能的某一段描述就行。用不着的技能可以归档，新能力可以作为一个新技能加进去，不需要去翻旧对话里的临时配置。

第三，可观测性。技能是结构化的，意味着每一次触发、每一步执行、每一次成功或失败都可以被记录和分析。裸的提示词没有这层能力，你根本不知道Agent哪一步理解偏了。

这三个问题不是某个框架特有的，而是所有想把Agent推向实际生产的人都躲不开的。所以无论你用的是哪家模型、哪个Agent平台，技能化的思路都能借鉴过来。

2. 技能库的基本盘：目录结构、SKILL.md 与技能命名规范

2.1 一个最小可用技能长什么样

以我日常使用的技能目录为例，我通常把技能统一放在项目根目录下的 skills/ 文件夹中：

skills/ ├── collect_changelog/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── fetch_commits.py │ │ └── format_markdown.py │ └── references/ │ └── output_template.md ├── triage_issues/ │ ├── SKILL.md │ └── scripts/ │ └── classify.py └── generate_weekly_report/ ├── SKILL.md └── templates/ └── weekly_report.md

每个技能一个独立文件夹，至少要有一个 SKILL.md 作为入口，其他辅助资源（脚本、模板、参考文档）按需放置。

这个结构有两个好处：一是每个技能自包含，复制整个文件夹就能共享；二是Agent加载技能时，能根据 SKILL.md 快速判断"这个技能是做什么的、该不该用、怎么用"，不需要把整个目录都塞进上下文。我在给团队搭技能库时，第一条规范就是：所有技能强制使用同一目录约定，禁止在技能文件夹外散落相关文件。

2.2 SKILL.md 里到底该写什么

SKILL.md 是技能的核心，它的质量直接决定Agent能不能正确触发技能、能不能正确执行。我写的 SKILL.md 至少包含四块内容：

第一块是 name 和 description。description 最关键，它是Agent判断触发条件的依据。写得越具体，误触发概率越低。不要只写"用于整理问题清单"，要写清楚适用的任务类型、输入是什么、输出是什么。我会在 description 里放两三个触发示例，比如"当用户提到'整理这周的更新日志'时使用"，同时写上反例，比如"当用户只是随口询问仓库状态时，不触发本技能"。

第二块是适用场景与边界。明说哪些情况适合用，也要明说哪些情况不适合。边界写得越清楚，Agent越不会把技能用在错误的地方。比如我之前写的一个技能，适用场景是"仓库托管在GitHub、issue数量超过20条"，边界条件写的是"如果issue数量小于5条，直接手动整理即可，无需启动技能"。

第三块是执行流程。大步骤写清楚：先做什么、再做什么、关键判断点在哪、每个步骤的输出怎么传给下一步。我试过两种写法，一种是自然语言段落，一种是带编号的操作清单。实测下来，对执行类任务，编号清单的效果明显更好，Agent很少跳步；对创造性任务，自然语言段落更合适，能留出发挥空间。

第四块是约束与规范。比如"所有输出使用中文""涉及金额的字段保留两位小数""不要修改指定分支以外的代码"。这部分是踩坑后不断补充出来的，它让技能的执行结果保持稳定。每次出现一次"输出格式不符合预期"的反馈，我都会先检查是不是约束没写到位，而不是急着改系统提示词。

2.3 技能动作的拆分原则：workflow 与 tool_use 的边界

技能内部的动作，我按这个边界来拆：需要调用外部接口、需要访问文件系统、需要执行明确计算逻辑的，放在 scripts 里用代码实现；需要根据上下文进行判断、比较、选择的，放在 SKILL.md 里用自然语言描述处理原则。

举个例子，"整理更新日志"技能里，"从Git历史中拉取某个时间段内所有commit信息"是明确操作，用脚本实现最合适，传入开始时间和结束时间，返回结构化数据。而"判断哪些commit属于功能开发、哪些属于修bug、哪些属于测试优化"这种语义判断，我不会写死在代码里，而是把分类标准写成描述性规则，让Agent在执行时灵活判断。

这么设计的原因，底层逻辑很简单：代码擅长确定性操作，自然语言擅长模糊判断。确定性逻辑用代码，既能避免Agent每次执行结果飘忽不定，也能节省Token；模糊判断用自然语言描述规则，保留Agent的灵活性。两者结合，技能才不会僵硬。我见过不少人把语义判断也硬编码成规则引擎，结果维护成本直线上升，因为真实世界的判断边界根本列不完。

3. 手写一个可落地的技能：以"批量整理代码仓库更新日志"为例

3.1 需求拆解：不急着写代码，先想清楚边界

假设我现在要给项目做一个 collect_changelog 技能。第一步不是写 SKILL.md，而是想清楚这个任务的边界：

• 输入：一个时间范围（可选，默认最近一周）、一个目标仓库路径
• 输出：一份按类别分组的更新日志，markdown格式
• 处理逻辑：先拉取commit历史，再做语义分类，再生成日志文件

这个过程中，"分类"最容易有歧义。同一批commit，"feat: add login page" 毫无疑问是功能，"fix: user avatar not loading" 是修复，那"chore: update dependencies"算什么？"refactor: split utils into modules"又算什么？分类规则必须写清楚，否则Agent每次分类都可能不稳定。

我把分类定义成五类：功能、修复、优化、重构、其他。每个类别给出典型示例和边界说明。比如"优化"限定为性能调优、加载速度改进、资源占用降低，"重构"限定为不改变外部行为的代码结构调整。有了这些界定词，Agent的分类稳定性会明显好于没有示范的情况。这个拆解工作大概会花掉整个技能开发的三分之一时间，但省下来的调试时间远不止这些。

3.2 技能文件夹的完整内容清单

collect_changelog 技能的完整文件清单是：

skills/collect_changelog/ ├── SKILL.md ├── scripts/ │ ├── fetch_commits.py # 拉取指定时间段的commit（支持按分支过滤） │ └── generate_report.py # 将分类结果渲染为markdown更新日志 └── references/ └── category_guidelines.md # 分类规则的详细说明与示例

SKILL.md 描述整体流程和触发条件；fetch_commits.py 只负责和 git 命令行打交道，不涉及任何语义判断；generate_report.py 接收分类后的commit列表，按照模板生成日志；category_guidelines.md 里是详细分类示例。脚本建议用标准库或极简依赖实现，因为技能库要在不同机器上复用，依赖越多越容易在各种环境里翻车。

3.3 写 SKILL.md 时的关键措辞：描述越具体，触发越准确

SKILL.md 的 description 我会反复打磨。初稿可能是"生成项目更新日志"，二稿改成"从Git仓库获取指定时间段的提交记录，按功能、修复、优化、重构、其他五大类整理成更新日志，输出到指定文件"，三稿还要加上触发示例："当用户提到'整理这周的更新日志''生成release notes''汇总commit记录'等需求时使用"。

这里的逻辑是：Agent触发技能依靠的是 description 和用户指令的语义匹配，触发示例能显著提升匹配准确率。只写一句"生成更新日志"，Agent可能在用户只是想简单聊两句的时候就把技能全套加载进来，白白浪费上下文；加上触发示例和反例后，误触发率能降一大截。我做过一个统计，优化 description 前后，同一个技能的误触发次数降了差不多三分之二。

还有一个小细节：description 里不要用太多修饰性词汇。比如"高效地""智能地""自动地"这类词，对Agent理解触发条件没有帮助，反而可能干扰语义匹配的权重。直接说做什么、什么时候用、输入输出是什么，最有效。

3.4 从主Agent到技能内部的多步流程设计

技能触发后，Agent 执行的主流程我写成这样：

1. 分析用户指令，确认时间范围和仓库路径，缺失的按默认值或主动询问
2. 调用 fetch_commits.py 获取 commit 列表
3. 读取 references/category_guidelines.md 中的分类规则，对 commit 逐条分类
4. 调用 generate_report.py 渲染 markdown 报告
5. 将报告输出给用户，并提示是否可以写入文件

注意第3步，我刻意让它"读取分类规则"而不是"在SKILL.md里内嵌分类示例"。原因是：SKILL.md 会被Agent全文加载，写太长会占用大量上下文；references 里的文件是按需读取的，只在真正需要分类的时候才加载。这也是技能内部资源组织的一个重要原则——能按需加载就别一股脑塞进去。

实际执行时，Agent 可能会在步骤2和步骤3之间来回跳几次，比如发现 fetch_commits.py 输出的数据格式和预期不符，会回头检查脚本参数。这很正常，技能流程设计不该是死板的瀑布流，只要 Agent 最终能走通并且结果稳定，中间的微小折返是可以接受的。

4. 技能仓库的组织与管理：版本、依赖与多Agent复用

4.1 用Git管理技能库的注意事项

技能本质上也是代码资产，我的习惯是把技能放进单独的Git仓库，与主项目仓库分开。原因是技能的变更节奏和主项目不一样——主项目按功能迭代，技能按执行行为迭代。混在一起，历史记录会变得很乱，回滚也容易误伤。

在技能仓库里，每个技能的开发主线大致是：

• v1.0：初版，能跑通基本流程
• v1.1：补充分类边界描述，修复误分类
• v2.0：把输出模板改成 references 引用，SKILL.md 瘦身

每条提交信息我都会写清楚改动的影响范围。比如"将分类规则迁移到独立引用文件，SKILL.md 字数减少约40%"，这种信息在日后排查问题时非常有价值。另外，技能仓库的 README 里我维护了一个技能清单表格，列出每个技能的名称、版本、适用场景和负责人，避免团队里出现"这个技能是谁维护的"这种问题。

4.2 技能间依赖怎么声明

技能之间难免有依赖。最简单的做法是在 SKILL.md 里加一个 dependencies 字段，声明依赖的其他技能和版本范围。当Agent加载当前技能时，如果发现依赖缺失，可以先技能库拉取对应技能，再继续执行。

需要特别提醒的是，依赖关系别设计得太深。我见过有人把技能A依赖技能B、技能B又依赖技能C，结果一次触发连锁加载了十几个技能，上下文直接爆掉。我的建议是尽量保持技能扁平：如果一个技能里涉及复杂的跨领域能力，优先拆出来作为独立任务执行，而不是层层嵌套。依赖深度控制在两层以内，是我实测比较稳妥的阈值。

4.3 多场景复用：个人助手、团队机器人、流水线Agent

技能库的一个显著优势是：同一套技能可以在多个场景复用。我在个人开发环境维护的技能库，被用在几个地方：

• 个人命令行Agent：整理更新日志、提交PR前的自查、代码review辅助
• 团队协作机器人：自动整理每日站会纪要、自动处理issue triage
• CI流水线：发布前自动生成release notes

这几个场景共享同一套技能定义，只是执行入口和权限边界不同。实际运行下来，维护收益远超维护成本——改一次分类规则，三个场景同步生效，不用去翻分散在各处的提示词。我算过一笔账，技能库投入的维护时间，换来的收益大约是原来逐个场景维护提示词的三到四倍。

5. 实测中踩过的坑：上下文溢出、技能误触发与回退

5.1 技能误触发：description 写得含糊的后果

最典型的翻车案例：我给一个 write_commit_message 技能写描述时，只写了"根据代码变更生成提交信息"。结果我发现，每当用户提到"提交"两个字，Agent 都尝试触发这个技能——哪怕用户只是在说"我提交了一个bug，你有空看看"。

解决这个问题，我用的是三个手段组合：在 description 里增加明确的触发信号关键词、增加反例描述、补充不适用场景。三点缺一不可。调整后的描述是："当用户需要对已修改的代码生成 git commit 信息时使用。仅适用于用户明确表达需要编写或优化提交信息的场景。若用户只是在讨论代码问题、报告提交行为，不触发本技能。"

这种修正在技能上线初期特别重要。我的经验是：新技能上线第一周，每天都要翻一遍触发日志，看到不合理的触发就立刻调整描述。熬过这一周，后面就稳定了。

5.2 长技能导致上下文被占满

技能本身写得越长，Agent加载时占用的Token就越多。我踩过一个很具体的坑：一个技能文件4000多字，其中一半是详细的操作步骤，另一半是大量示例。每次触发这个技能，光加载它就要消耗大量Token，遇到复杂任务加上对话历史，上下文很快就紧张了。

后来的调整是大动作：把不变的静态内容尽量外置到 references/ 等按需加载的位置；把动态执行路径留在 SKILL.md 里，控制在一两千字以内。这个调整立竿见影，触发技能的Token开销降了不少，而且因为Agent每次只在需要时去查参考文档，反而比一股脑全加载更准确。

这背后其实是上下文资源管理的问题。Agent的上下文窗口不是无限的，技能体系设计得越精细，就越要把上下文留给真正需要实时推理的部分，而不是被静态描述占满。

5.3 技能内部步骤失败时的回退策略

技能是按流程走的，但流程中的任何一个步骤都可能失败：git历史拉取失败、文件路径不对、格式转换报错。Agent默认的行为通常是直接报错退出，但更好的做法是给它一套回退规则。

我在 SKILL.md 里加了一段"失败处理"说明。比如：拉取commit失败时，先检查仓库路径是否存在；确认路径没问题后，尝试用轻量级命令重新拉取；如果依然失败，把错误信息返回给用户，并建议检查git仓库状态或权限配置。这套回退规则看起来简单，但在生产环境里作用非常大。它能避免Agent因为一个小异常就放弃整个任务，也能避免它在同一个地方反复重试浪费Token。

我还把"失败处理"单独作为一个子段落写进 SKILL.md 的标准模板里，这样所有技能默认都有一套基本的容错策略，而不是每个技能各自为政。

5.4 日志与可观测性：给技能加 trace

技能执行完到底好不好用，不能全靠感觉。我在技能库里给每个技能的执行过程加了轻量级日志：触发时间、触发的用户指令、技能内部执行了哪些步骤、每步耗时、最终是否成功、Token消耗。这些数据汇总下来，就能看到哪些技能被频繁误触发、哪些技能成功率低、哪些步骤消耗过大。

这个习惯是我吃了大亏之后养成的。之前有一个技能，提示词越写越长，但完全无法判断到底是哪一步拖慢了执行速度、哪一步引入了不稳定因素。后来加了日志，一眼就看到问题出在一个频繁调用的外部接口上——它平均耗时要占到整个技能执行时间的80%。优化了那个接口之后，整个技能的执行时间缩短了一半。

所有把技能库用于生产环境的朋友，我的建议是：可观测性第一时间加，越早越好。等出了问题再去补日志，往往要牺牲一部分历史数据才能获得足够多的有效样本。

6. 技能评估与持续迭代：让技能库越用越顺手

6.1 评估维度：准确率、完成率、耗时、Token消耗

技能不是写完就结束了，它需要持续评估。我通常从四个维度去看一个技能的健康状况。

准确率：输出结果是否符合用户预期。这个指标需要人工参与判断，我每周抽样一部分执行记录来复核。完成率：触发后从头到尾完整跑完的比例，可以从日志直接统计。耗时：从触发到输出结果的时间，如果某个技能耗时异常，往往是某个步骤出现了退化。Token消耗：技能加载和执行的总Token数，这个指标直接关系到成本控制和上下文预留。

这四个维度合在一起，能比较全面地反映一个技能的真实工作状态。单一维度的优化没有意义，比如把 Token 压得很低但完成率掉了一半，那就是得不偿失。

6.2 回归测试：给技能配"习题集"

技能迭代很容易引入"修好一个坑又弄坏另一个坑"的问题。我的做法是给每个技能配一份回归测试集，里面放上典型的输入样例和期望的输出结果。每次改技能，先在测试集上跑一遍，确认没破坏旧场景。

一个技能的测试集不需要太多，五八个经典案例就够用，关键是要覆盖边界情况。比如分类技能，测试集里一定要有"既有功能又有修复的混合commit"这类不太好分类的样例。我见过有人给技能配了五十多个测试案例，维护测试本身的成本反而超过了技能迭代的收益，不划算。

回归测试的执行也不一定非要自动化。我目前是半自动方式：手动触发一轮测试集，人工比对输出结果，记录在技能仓库的 CHANGELOG 里。等技能数量超过一定规模后，可以再引入自动化测试工具。

6.3 技能版本更新的灰度策略

技能更新最好不要直接全量替换。我踩过"新版本技能在A场景表现好，在B场景直接翻车"的坑：当时把一个新的分类规则直接推上去，结果旧场景里原本分类准确的commit全被错误地归到了"优化"这一类。恢复还花了点时间，因为有些日志已经被覆盖了。

现在的做法是：技能描述里增加版本号字段，新版本先标记为 beta，只有收到明确使用 beta 的指令时才加载新版本；跑了一段时间，确认各场景稳定后，再把正式版本号切到新版本。这个灰度过程听起来有点重，但跟一次技能回归失误造成的损失比起来，这点成本完全可以接受。

尤其是运行在团队协作机器人这类面向多人的场景里，一次技能回归失误，影响的不只是一个人，可能整个团队的自动化流程都会跟着出问题。灰度策略相当于给技能迭代上了一道保险。

技能库维护到现在，我最深的感觉是：它不是一件做完就放在那里的静态资产，而是一个需要持续浇水修剪的花园。每次踩坑、每次规则调整、每个新场景的接入，都会让技能库变得更成熟。如果你也在带着Agent往生产环境走，我的建议是从一开始就用技能化的思路去组织它的能力，哪怕前期看着麻烦，跑过一两个月之后，你会庆幸当初做了这个决定。