企业官网建设流程全解析

把 Agent 项目里的“说明书”升级成“技能包”，是最近我做得最值的一件事。先说结论：Skills这个概念，本质上就是把过去散落在系统提示词、工具函数和项目文档里的能力碎片，重新打包成一个个有边界、可复用、能测试的模块。我是在一个内部自动化项目里被逼着走通这条路的，最开始所有指令都堆在 system prompt 里，结果上下文越塞越满，改一处流程要连带调整好几段不相关的逻辑，调试体验非常差。后来接触到 Skills 机制，才发现之前踩的坑几乎都不该踩。

这篇文章就围绕 Skill 的设计、编写、调试和进阶来做完整拆解。适合正在做 Agent 应用、想优化提示词工程、或者单纯觉得“让 AI 稳定干活很难”的朋友。我尽量把每一步讲透，包括为什么这么做、实际踩过的坑、以及可以直接抄走的技能包模板。

1. 为什么我把 Skills 当成 Agent 项目里的“一等公民”

1.1 先看看没有 Skills 的时候我在怎么干活

最早我做 Agent 自动化，思路很朴素：把所有流程说明都塞进系统提示词，再把所有外部操作都做成 function calling 工具。看起来挺完整，但用起来问题一个接一个。

第一是上下文爆炸。一套完整的业务流程，少说三四千字，多则上万字。每次对话都会把这些内容重新加载一遍，模型能记住的“注意力”就这么多，真正的用户问题反而得不到足够重视。这就好比一个新人刚入职，你把一百页的手册一次性丢给他，要求他背下来再干活，结果他连你今天交代的重点是什么都没记住。

第二是修改成本高。流程里的任何一个环节发生变化，比如某个工具的调用参数改了、某个步骤顺序调整了，你就得在提示词里找到对应位置，小心翼翼地修改，还不能保证这次修改不会影响其他无关流程。改着改着，你会发现提示词变成了一个只有你自己能读懂的意大利面条。

第三是毫无复用性。A 项目里写好的数据处理流程，换到 B 项目完全拿不过来，只能复制粘贴再改一遍。更麻烦的是，这些流程和具体的提示词上下文纠缠在一起，根本没法做成独立模块。

1.2 Skills 的抽象方式：把“流程 + 脚本 + 知识”装进一个文件夹

后来我接触到 Agent Skills 机制，核心思路其实很简单：一个技能就是一个文件夹，里面包含一份 Markdown 格式的技能说明书（通常叫 SKILL.md）、一个放脚本和代码的scripts目录，以及一个放参考资料或静态文件的assets目录。Agent 在运行过程中，会根据用户的需求去检索最匹配的技能包，加载它的说明书，再按说明书里的步骤去执行脚本。

这个设计好在哪里？用一个类比来解释：过去你是在对话里“手把手教一个聪明但没经验的新同事做事”，你说的每一句话他都要消化，但可能转头就忘；而 Skills 是“直接递给这位同事一本标准作业手册”，他甚至不需要背诵，只需要在遇到对应任务时翻开手册，照着流程走就行。

手册里写清楚了什么场景下用、具体分几步、每步做什么、调用什么脚本、遇到异常怎么处理。手册不需要一直放在口袋里，需要用的时候再拿出来。这个天然的“按需加载”特性，直接解决了上下文爆炸的问题——没被选中的技能包根本不会占用任何对话空间。

1.3 选型之后的收益：可测试、可组合、可排错

把能力模块化以后，很多工程上的好处会自然涌现。比如可测试性：你不需要关心提示词怎么写才能触发某个行为，直接测试技能包在输入特定参数时，脚本层能不能给出正确结果即可。一个技能包就是一个黑盒，输入、输出、异常都清晰。

还有可组合性。拿我手头的一个数据报表项目来说，“拉取数据”是一个技能，“清洗数据”是一个技能，“生成图表”是另一个技能。在某个具体任务里，Agent 可以在说明书里写明“如果需要生成图表，请先调用拉取数据技能，再调用清洗数据技能”，技能包之间形成了清晰的流水线关系。这种组合方式比在提示词里用自然语言描述调用关系要可靠得多。

排错也变得更舒服。过去流程出错，你得去猜是模型理解错了、提示词写错了、还是工具调用时序错了。现在直接定位到具体技能包，查看它的脚本日志、说明书步骤、以及 Agent 是否选对了技能，几步就能锁定问题范围。

2. 一次完整上手：从零设计一个图片压缩技能包

2.1 需求场景与设计思路

我用一个非常容易复现的例子来演示整个流程：做一个图片压缩技能包。场景是用户丢给你一个图片目录，要求“把图片压缩一下，方便发到微信群里”。

普通做法是在系统提示词里写：“如果你收到图片压缩需求，请使用 PIL 库遍历目录下的图片，将体积较大的图片压缩到指定质量。”这样写在单一场景下够用，但一旦用户问“只压缩 PNG 格式”、或者“把图片和文档一起打包发送”，规则就开始互相干扰了。

正确的做法是把它封装成独立的技能包。我管它叫image-optimizer。先规划好技能包内部结构：

image-optimizer/ ├── SKILL.md ├── scripts/ │ └── compress_images.py └── assets/ └── size_guide.txt

SKILL.md是说明书，scripts目录放核心逻辑，assets目录放模型执行时可能需要参考的资料（比如“不同平台推荐图片大小”这类知识库文档）。

2.2 编写 SKILL.md：一份能让 Agent 照着执行的操作手册

SKILL.md是整个技能包的大脑。它分为两部分：头部元信息（frontmatter）和正文指令。frontmatter 里的name和description直接决定了 Agent 在什么时候唤起这个技能包；正文则是一份逐步执行的操作说明。

我建议的最小可用模板是这样：

--- name: compress_images description: 压缩图片、减小图片体积、调整图片分辨率、优化图片尺寸时使用。适用于用户指定目录下的图片文件。不适用于视频、PDF、压缩包。 --- # 压缩图片 ## 前置条件 1. 确认用户提供的源目录存在，且目录中包含图片文件（扩展名为.jpg/.jpeg/.png/.webp）。 2. 如果源目录不存在，先向用户确认正确的路径，不要自行猜测。 3. 确定输出目录，默认在源目录下创建 compressed 子目录。 ## 操作步骤 1. 调用 `python3 scripts/compress_images.py --input <源目录> --output <输出目录> --quality 80`。 2. 等待脚本执行完成，读取控制台输出。 3. 若输出中显示有失败文件，则针对失败文件单独报告给用户，并说明失败原因。 4. 压缩完成后，统计压缩前后的总体积与压缩比例，写入最终回复。 ## 常见异常 - 如果提示缺少 Pillow 库，先执行 `pip install Pillow`。 - 如果目录里没有图片，告知用户该目录没有可压缩的图片，而不是报错。

这段说明有几个细节值得注意：description 里我明确了“什么时候用”和“什么时候不用”，这是为了让 Agent 能精准匹配用户需求，同时避免和其他技能包竞争；正文里的步骤全部编号且可操作，每一步都对应一个明确的动作；异常处理写进了技能包里，不需要用户在对话里反复澄清。这比在系统提示词里写一堆“如果出现xx异常，请如何如何”要规整得多。

2.3 配套脚本：让说明书里的步骤真正落地

说明书写得再好，最后还是要靠代码干活。compress_images.py不需要写得多复杂，但有几个工程细节值得分享。

第一，脚本必须能独立运行、独立测试。不要把逻辑写成只有 Agent 才能调用的函数，而是用标准命令行参数接收输入，这样你在调试时可以直接跑脚本看效果，完全不依赖模型。

第二，输出要给足信息。脚本执行完，我要求它输出压缩前后的文件体积、处理文件数、失败文件列表。这些信息会让 Agent 在最终回复里给出有依据的数据，而不是凭空总结。

第三，异常要写得具体。比如“图片格式不支持”“文件正在被占用”，这些错误信息最终会原样传到 Agent 的上下文中，写得越具体，Agent 越容易给出正确的处理建议。

核心脚本的核心逻辑，其实就是三件事：遍历源目录、按质量参数压缩、写出到目标目录。用 Python 的 Pillow 库几十行就能搞定。

2.4 测试技能包：模拟真实用户请求做冒烟测试

技能包写完后，不要直接拿去接对话流程。我习惯先用最小测试集做冒烟测试——准备一个包含不同格式、不同大小图片的测试目录，然后手动触发一次 Agent 调用，观察它是否选中了正确技能、是否顺利执行脚本。

这里有一个容易忽略的点：Agent 选中技能包靠的是description和用户意图的语义匹配。如果你的描述写得太业务化，比如“执行图片压缩流程”，用户换个口语化的问法“把图片变小点”，模型可能就匹配不上了。我的经验是，在 description 里尽量罗列同义表达：“压缩”“变小”“减小体积”“优化尺寸”“压一下”，覆盖率越高，触发越稳。

冒烟测试没问题后，再扔几个边界问题给它：空目录、不存在的路径、带特殊字符的文件名。这些场景不需要提前写好答案，关键是观察技能包在异常情况下会不会优雅地反馈，而不是卡在半路让用户干等。

3. 技能包的内部结构解析：描述词、步骤指令与依赖管理

3.1 description 是最被低估的入口设计

很多人写技能包，把 90% 的精力花在操作步骤上，却忽略了description里的几十个字。但我要说，description决定了你的技能包有没有机会被使用。

为什么这么说？因为 Agent 在选择调用哪个技能包时，本质上是做一次检索和匹配。它读到的第一个文本就是description。如果你写得含糊，比如“负责图片相关事务”，那模型面对一个“把图片改成黑白”的需求，也可能会唤起这个技能包，然后你的脚本可能并不支持灰度化，流程就崩了。

我建议的写法是：先说触发条件，再说输入参数，最后说边界。正面例子是“用户要求压缩、减小图片体积、调整分辨率时使用；输入为源目录路径与输出目录路径；不处理视频和PDF”。反面例子是“图片处理工具”。一个好用的技巧是：写完 description 后，自己试着用五个不同的问法去触发它，如果连着两个问法匹配不上，就继续补同义词。

3.2 操作步骤指令：少一点“尽量”，多一点“必须”

SKILL.md 正文里的操作步骤，本质上是在给 Agent 写一份执行脚本。但很多人会不自觉地写成“发挥题”：比如“对图片进行高质量压缩，确保效果美观”。这种描述的好处是给了模型自由发挥的空间，坏处是你无法预测它会怎么发挥。

我自己的原则是：凡是预期的行为，就是“必须”句式；凡是允许模型自己做判断的地方，才用“可以”句式。举例来说：“压缩后必须删除源文件”和“如果压缩后体积仍然超过 100KB，可以尝试二次压缩”。前者是硬性规则，不允许偏差；后者是优化策略，给模型留出判断空间。

另外，步骤指令不要追求“全”，要追求“够”。如果一个技能包需要 40 步指令才能讲清楚，大概率不是指令没写好，而是这个技能的边界划得太宽了。试着把它拆成两个更聚焦的技能包，Agent 的调用准确率和执行稳定度都会明显改善。

3.3 依赖声明：让技能包可以“随身携带”

如果脚本依赖第三方库，我建议直接在 SKILL.md 里写清楚依赖关系，比如：

pip install Pillow

这不是可有可无的信息。试想一下，你的技能包被复制到另一个项目里，Agent 第一次执行脚本就报“ModuleNotFoundError”，如果你在说明书里预先告诉它“本脚本依赖 Pillow，如缺失请先安装”，模型就能自主完成环境修复，而不是卡在第一步换一种方式反复报错。

更重要的是版本。依赖库一旦升了大版本，可能 API 就变了。我在 SKILL.md 里会额外注明“测试环境为 Python 3.10 与 Pillow 10.x”，这样后续维护的人（包括未来的我自己）能够快速判断问题出在环境还是出在代码。

3.4 assets 目录：把“参考资料”和“可执行指令”分开

我见过不少技能包，把所有知识都写进 SKILL.md，变成一份几万字的巨型文档。这个思路有问题——SKILL.md 每次被调用都会完整加载，占用大量上下文，而这些知识里可能 80% 在当前任务里根本用不上。

正确的做法是：把高频执行指令留在 SKILL.md，把低频参考资料放在assets目录。比如在图片压缩技能包里，assets/size_guide.txt可以记录“微信封面建议 900×383，公众号头图建议 900×500”这类平台规范。SKILL.md 里只需要写一句话：“如需平台推荐尺寸，请阅读 assets/size_guide.txt 文件”。

这样做的收益是双重的：日常执行时上下文保持精简，只有在模型确实需要参考规范时，它才会去读取那个文件。这种“懒加载”机制，是让技能包在长对话场景下依然保持高效的关键。

4. 调试实录：技能不触发、输出不稳定、上下文被塞满怎么办

4.1 问题一：技能包永远不被触发，怎么调都无效

这是新手最容易遇到的拦路虎，也是最让人抓狂的问题。排查了几个项目后，我发现原因几乎都出在description上——它和用户口语表达之间的语义鸿沟太大。

举个具体的例子：一个做会议纪要的技能包，description 写的是“总结会议记录并输出行动项”。用户问的是“帮我把刚才的录音整理成待办事项”，模型没有识别出“整理成待办事项”和“输出行动项”是同一个需求，于是技能包被晾在一边，模型开始自己用通用的总结能力硬答。

排查方法很简单：把用户可能说的每一种口语表达列出来，逐个对照 description 里的关键词。如果不匹配，就扩充描述词。不要觉得这是在做“同义词替换”的笨功夫，实际上这就是在教模型做更加精确的语义映射。还有一个排查技巧：使用支持“思考过程输出”的调用方式（如果有推理日志），看看模型在选择工具时实际考虑了哪些描述文本。日志是最好的老师。

4.2 问题二：脚本执行报错，但报错信息对模型毫无帮助

脚本本身写得没问题，真正执行时报了一个 Python 的原始异常，AI 完全不知道该怎么处理。这个问题本质上是“错误信息的设计问题”。

我自己写的脚本，会在关键节点主动捕获异常，并输出带上下文的信息。比如：

except Exception as e: print(f"[ERROR] 图片 {filename} 压缩失败，原因: {e}，请检查文件是否损坏或格式是否支持。")

这样 Agent 看到错误信息时，知道“哦，是某个具体文件坏了”，它就能给出更有针对性的建议，比如“这个文件损坏了，建议换个文件试试”，而不是面对一行OSError无从下手。记住一个原则：脚本里的每一个报错，都应该像写给用户的客服话术，而不是写给程序员的堆栈日志。

4.3 问题三：技能包内容太长，还没干活上下文就被吃掉了

技能包的说明书动辄上千行，每调用一次都会完整进上下文。当多个技能包轮流调用时，上下文空间快速告急，模型开始“前听后忘”。

我的解决方案是前面提到的分层设计：指令部分只保留核心流程，长篇的规则文档一律移到assets，由模型按需读取。另一个思路是，把一些“几乎每次都要用的默认行为”从技能包里抽出来，放进系统提示词；把“偶尔才用一次的特殊流程”留在技能包里。这样每天共用的是系统提示词，占用的上下文只计算一次。

4.4 问题四：多个技能包互相竞争，同一个需求会触发错误技能

当技能包多了以后，会出现“抢单”现象。比如用户说“把这段文字压缩一下”，你的“文本摘要技能”和“文本压缩技能”都会匹配上，模型可能选了一个语义上并不贴合的。

解决方法是给每个技能包的 description 增加边界声明，把“不属于本技能处理范围”的情况明确写出来。比如文本压缩技能描述可以加一句：“本技能只处理文章内容压缩（删减冗余表达），不用于生成摘要、不用于代码压缩。”语义边界越清晰，模型的选择就越准确。

4.5 排查工具与流程小结

我做技能调试时，喜欢把排错流程固化下来：

这个表格帮我节省了大量重复排查时间，现在每次新技能包上线，我都会按这个顺序预检一遍。

5. 进阶玩法：技能组合、版本管理与团队共享

5.1 技能组合：让一个技能在流程中主动调用另一个技能

当技能包积累到一定数量，你自然会发现它们之间可以串联。比如我的“数据报表项目”里，“拉数据”“清洗数据”“转 Excel”就是三个独立技能包，但它们在流程上是强依赖关系。

实现技能组合的方式并不复杂：在某个技能包的 SKILL.md 里，直接声明依赖关系。比如“生成 Excel 报表”技能的操作步骤里写：

1. 如果用户提供的是原始数据文件，先调用 data_cleaner 技能完成数据清洗。 2. 清洗后的数据写入临时目录。 3. 调用 `python3 scripts/build_excel.py --input <临时目录> --output <目标目录>`。

Agent 在读到这一步时，会自主去检索并调用data_cleaner技能包。这种“技能包间调用”的能力非常有价值，它让一个复杂的任务不用写在一个巨大无比的单体技能里，而是由多个小技能包协作完成，每个小技能包依然保持简单、稳定、易调试。

设计组合关系时要注意一个原则：只允许上层技能声明下方技能的调用，不要出现循环依赖。A 调 B、B 调 C 没问题，A 调 B、B 又调 A 就是灾难。我习惯在技能的依赖声明里加一个“上游/下游”的注释，方便日后维护。

5.2 版本管理：把技能包当代码库来维护

技能包的迭代速度和普通代码一样快，甚至更快——因为你今天发现 description 写得不够好，明天可能就要更新。所以一定要用 Git 管理技能包的仓库。

我做版本管理时坚持三个习惯。第一，每个技能包是一个独立的目录，有自己的 README 和 CHANGELOG。CHANGELOG 里记录每次变更的内容和原因，比如“v1.1 扩大描述词覆盖范围，解决口语化问法无法触发的问题”。第二，使用语义化版本号（SemVer），主版本号在技能包结构或核心流程变更时递增，次版本号在新增功能时递增，补丁号在修复小问题时递增。第三，修改前先写测试用例。我最低限度的测试是准备一组固定输入，要求技能的脚本在三次运行中给出相同结果，并且结果符合预期。这听起来很简单，但能拦截掉相当一部分“重构改坏”的情况。

5.3 团队共享：建立技能包评审机制

当团队多人都在向 Agent 项目贡献技能包时，就需要一个评审机制来保证质量。我在团队里推行过一个“技能包入库检查单”：

• 技能包目录结构是否符合规范（SKILL.md / scripts / assets 齐全）
• SKILL.md 的 description 是否包含清晰的触发条件和边界
• 操作步骤是否可执行，是否包含异常处理说明
• 脚本能否独立运行，是否输出结构化执行日志
• 依赖是否在说明文档中声明
• 是否附带最小测试用例

一张检查单解决了很多协作问题。因为技能包的质量标准被显式化之后，评审不再是靠感觉，而是逐项对照。新成员提技能包之前自己就会对着检查单过一遍，大大减少了来回打回修改的时间。

5.4 再聊一个我自己踩过的坑

最后多提一嘴，如果你准备在自己的项目里引入 Skill 机制，最大的坑可能不是技术，而是“过度设计”。我第一次尝试时，恨不得把所有功能都拆成技能包，连“输出一句话”都要建一个技能。结果技能包数量上来了，Agent 的检索负担反而更大了，经常在好几个技能之间犹豫不决，响应速度变慢。

后面我给自己定了一个简单标准：如果一个功能只用一次，或者一个流程短到能在系统提示词里用三句话写完，就不要单独做技能包。技能包的收益来自复用和隔离，一个小而常用的功能做成技能包是值得的；一个只在这个项目里用一次、又短又简单的功能，做成技能包纯属给自己找麻烦。

根据我个人经验，从三五个核心技能包开始，跑通整个流程后，再慢慢扩展，是入门 Skill 机制最平滑的路径。希望这篇文章能帮你少走一些我走过的弯路。