企业官网建设流程全解析

前阵子朋友圈和各个技术群里都在聊 agent-skills，一开始我觉得这就是把 prompt 拆成文件管理而已，没太当回事。直到我自己在一个真实的数据处理任务里，被一个超长系统提示词反复折腾到想砸电脑，才彻底明白：把经验沉淀成 Agent 可复用的技能包，不是换一种管理方式的问题，而是 Agent 应用能不能规模化的分水岭。

这篇不打算复述某个产品的新功能介绍，我想认真讲讲我搭建一套 Agent 技能体系时的完整思考：技能到底该设计到多细、目录文件怎么组织、Agent 靠什么机制自动发现技能、以及亲手踩过的几个典型坑。如果你正在做 AI Agent 开发，或者想把自己的工作流开放成其他人也能复用的技能，这篇应该能给你省下不少弯路。

1. 从“超长提示词”到“技能包”的转变：Agent 真正缺的是什么

1.1 大提示词方案在真实任务里是怎么失控的

早期我做的 Agent 应用基本都是“大 Prompt 引擎”路线：把所有业务规则、输出格式、参考示例、工具调用逻辑全部塞进系统提示词，靠模型强大的长文本理解能力硬扛。Demo 阶段这招确实爽，改个规则跟在大字符串里动刀一样，画面里演示得漂漂亮亮的。

但到了真实任务阶段，问题一个接一个。首先是上下文稀缺性问题：系统提示词占掉几千 token，用户真实输入的空间就被压缩，模型开始把精力分散在理解冗长的规则上，反而不关心用户的核心诉求。其次是排障成本，超过 1000 行以后，每动一个标点你都不敢大意，因为你永远不知道模型是根据哪一段话来理解规则的，回归测试成本高得吓人。

我自己遇到过最离谱的一次：给 Agent 写了 1200 多行的系统提示词，包含各种规则、格式模板、异常分支。结果在一个多轮任务中，模型直接把历史对话里聊天内容当成原始数据拿来处理，输出结果全乱套。排查到最后，问题根源竟然只是某一段关于“历史记录”的说明出现了歧义。那次之后我就下定决心，一定要把提示词里的业务流程拆出去，用独立的技能模块承载经验。

1.2 技能模块的实质：把隐性经验变成可加载的显性模块

好，那“Agent 技能”到底是什么。以目前主流 Agent Skills 生态里的常见设计为例，一个技能包通常就是一个自带结构说明的目录。目录名是技能名称，目录里面放一个 SKILL.md 作为技能说明书，说明书开头用 YAML frontmatter 写技能的名称和描述，正文是给 Agent 看的详细操作指南。技能用到的脚本、模板、依赖声明全放在同一个目录里，跟着技能一起走。

Agent 在启动或运行过程中，会收到一份技能库清单。当用户提出目标时，一个技能选择机制会根据描述和目标的相关度，把最匹配的 SKILL.md 内容动态注入到上下文里。模型读完这份说明书，就知道该调用哪个脚本、按什么顺序执行、遇到异常怎么处理，就好像临时拿到了一份带工具的任务手册。

这个机制最大的价值在于，它把过去散落在模型记忆力里的经验，沉淀成一个一个独立的、可版本化的模块。团队新成员可以直接读 SKILL.md 学习一个技能的使用方法，改一个技能时也只影响引用它的场景。想想以前，光靠对话让模型学会一套复杂的文件处理流程，每换一个 session 就要重新培训一次，现在技能一加载，过程线直接就回来了。

1.3 技能、工具函数、工作流：别把三层混成一层

这里想团队内部一个比较重要的认知对齐：技能不是工具的替代品，也不是工作流引擎换个名字。三者解决的问题层次完全不一样。我平时喜欢用一个比喻：工具是一个稳定的汽车变速箱，技能是维修手册加工具箱的组合，工作流则是整条运输线路的调度计划。

理解这个分层之后，你就不会出现“这个功能是不是用一个技能搞定”的困惑。功能调用就拆成工具，任务流程就做成技能，多步骤的运营流程交给工作流或元技能来编排，三个层次配合使用，边界才清晰。

2. 动手设计技能前，先想清楚这几条边界

2.1 什么任务适合做成技能，什么任务要重新考虑

做了一段时间技能沉淀，我总结出一条筛选标准：一个任务适不适合做成技能，看它是不是“流程相对固定，但执行过程需要大量判断”。比如把一份 PDF 转成结构化 Markdown——流程固定吧？但中间要判断页面里哪些是表格、哪些是正文、哪些需要 OCR，这种场景就非常适合技能化。再比如“根据销售数据生成周报”，格式是固定的，但每一周的数据情况不一样，模型需要挑选指标、判断异常、决定怎么渲染图表，这也是典型技能场景。

反过来，如果是“输入两个参数，返回一个结果”这种纯接口调用，做成技能就多余了。任何有清晰入参出参、不需要过多决策流的操作，都应该直接做成 Tool 或 MCP Tool。我之前就犯过错误，把一个数据库查询封装成了技能，结果模型每次都要通过说明文本来理解该调用哪个脚本，明明一条 function call 就能搞定的事情，活生生多消耗了几百 token，还增加了出错概率。

另外还有一个很容易被忽略的陷阱：凡是需要人在每个环节做最终决策的任务，都不适合直接技能化。比如“自动给客户发送邮件并确认回复”这种，中间可能涉及公司审批、客户隐私确认，你在技能里写再多的规则，模型也没办法替人拍板。这种任务硬往技能里塞，最后出来的效果一定是不伦不类，管理层也不敢真的放权。

2.2 我心中的好技能：五个可以直接照做的标准

经过反复重构，我现在要求团队里每个技能包必须同时满足下面五个条件：

1. 名称唯一且语义明确。技能名全部用连字符小写，比如extract-tables-from-pdf，一眼能看出用途。绝对不允许util1、cleaner这种名字，模型根本猜不到该在什么时候调用。
2. 描述面向模型检索。描述要写成“当用户需要……时使用”这种触发式句子，而不是“一个高效的数据清洗工具”。两个描述在人类眼里差别不大，在模型选择器里差别天差地远。
3. 输入输出边界清晰。SKILL.md 里必须写明输入参数、产出物、响应状态码，以及常见的失败原因。模型不会读你的代码，它全靠这份说明来理解脚本行为。
4. 依赖自包含。技能脚本所需的所有第三方库、工具、模型，都要在技能目录内声明清楚。不能假装环境里什么都有。
5. 可测试可观测。每个技能跑完后，必须有明确的日志输出和返回状态，模型才能判断下一步是继续还是要报错。

这五个条件不是花架子。第一个条件和第二个条件决定了 Agent 能不能在正确时机引用技能，第三第四个条件决定了引用了能不能稳定执行，第五个条件决定了出错了能不能迅速定位。我见过太多技能包，写得很漂亮，但模型执行时完全不知道脚本输出的是什么状态，最后只能强行猜，一猜就崩。

2.3 两个最容易踩的反模式：万能技能与模糊命名

新手第一次做技能库，十有八九会掉进同一个坑：想做一个“处理所有文档”的万能技能。PPT、PDF、Word、Excel 全往里塞，方法写了一大堆，功能覆盖极广。但实际用起来，效果非常差。原因很简单，技能选择靠的是描述和目标之间的语义匹配。当多个任务挤在一个技能里，描述只能写成又长又泛的大杂烩，模型每次匹配都像是在大商场里找一个没有标牌的小店，不是完全找不到，就是找错楼层。

正确做法是拆成一个个独立的小技能，每个技能专注一个过程：表格提取是一个技能，文档格式转换是一个技能，摘要生成是一个技能。每个技能的小体积、高清晰度，整体组合起来的覆盖面反而更大。技能库就像工具箱，任何一个工具箱里如果全是一把能拧所有螺丝的瑞士军刀，那绝不是好事，板手、扳手、套筒该分开就要分开。

另一个反模式是命名随意。早期我把一个技能叫process_data，几个月后自己都忘了它到底是清洗数据还是生成指标。后来团队明确规定，每一个新技能进库之前，必须先在全局技能清单里搜索一遍，确认没有同名、近义描述的其他技能。名字是给模型看的，也是给人类维护者看的，模糊命名的代价短期看不见，等技能库超过 20 个的时候就会集中爆发。

3. 搭建一套可复用的技能库：目录、文档与脚本的实战细节

3.1 整个技能库应该长什么样

一个能够长期演进的技能库，我建议从一开始就用仓库模式来组织，千万不要在项目里随便堆一堆 Markdown。以下是我的 agent-skills 项目重构后的目录布局，你可以直接抄：

agent-skills/ ├── skills/ │ ├── extract-tables-from-pdf/ │ │ ├── SKILL.md │ │ ├── extract.py │ │ └── requirements.txt │ ├── merge-sales-reports/ │ │ ├── SKILL.md │ │ ├── merge.py │ │ └── templates/ │ └── meta-skills/ │ └── monthly-report-pipeline/ │ └── SKILL.md ├── tests/ ├── prompts/ └── docs/

为什么单独建一个meta-skills目录？因为元技能本身也是一个技能，但它不直接执行脚本，而是负责把多个基础技能编排成完整工作流。把元技能单独分类存放，能够避免模型在选择阶段把一个“组织任务”的技能和一个“执行任务”的技能混为一谈。这个微小区分，在技能数量上来以后，对命中率的提升非常明显。

tests目录放的是每个技能对应的样例输入和期望输出，docs目录放的是给人类团队看的说明文档，prompts目录放的是系统提示词片段。这样一来，技能、测试、文档是三层独立结构，各自的演进节奏完全不一样，不会互相阻塞。

3.2 SKILL.md 的结构与写法：是说明书不是功能简介

SKILL.md 是 Agent 理解技能的唯一入口，写得不好，脚本写得再漂亮也白搭。一份合格的 SKILL.md 必须包含 frontmatter 和正文两部分。frontmatter 承担元数据，正文是行动指南。下面是我项目里的一个实际例子：

--- name: extract-tables-from-pdf description: 当用户需要从 PDF 文档中提取表格数据并输出为 CSV 或 Excel 时使用。适用于包含大面积表格的 PDF，例如财报、统计报表、合同附件。如果 PDF 本身是扫描图片且无可复制文本，必须依赖 OCR 能力；如果用户只需要提取文字而非表格，请改用其他技能。 --- # Extract Tables from PDF ## 适用场景 - 输入：PDF 文件路径或 URL - 输出：CSV 格式的表格数据，输出到用户指定目录 ## 执行步骤 1. 确认输入 PDF 存在，运行 `python extract.py <input.pdf> <output.csv>` 2. 脚本自动检测页面横线边界；对扫描件，自动调用 OCR 进行文字识别 3. 脚本返回状态码：0 表示成功，1 表示表格无法识别，2 表示输入文件不存在 ## 注意事项 - 表格超过 50 行时，输出文件会自动拆分，避免单个文件过大 - 若页面中表格横跨两页，脚本会尝试拼接，但拼接失败时不要静默跳过，必须输出告警

有几个写作重点值得强调。描述里面要写清楚“什么时候不能用”，这比写“什么时候能用”更重要。模型做技能选择时本质上是在做判断，你把排除条件写清楚了，它就不会在用户只是想要一段普通文本时强行触发技能转换。正文部分要按行动顺序组织，而不是按功能模块组织。模型执行技能时像在按流程单操作，你给它一份按模块写的数据字典，它还得自己拼装执行顺序，多一层推理就多一层出错风险。

3.3 技术依赖与路径问题：技能自包含的工程细节

技能最容易翻车的地方就是依赖环境。写技能脚本的人往往会假设“机器上应该装了什么”，但这种假设上线后一定会出问题。技能库里的每个脚本，我要求它必须自带依赖声明，并在入口处做显式检查。我举个实际例子，一个技能脚本的开头通常长这样：

python -c "import pandas" 2>/dev/null || { echo "依赖缺失: pandas"; exit 3; }

这一段的作用很直接：依赖缺了，立刻用状态码 3 告诉 Agent 当前环境不满足条件，而不是让脚本在运行时输出一堆莫名其妙的 Traceback，最后模型错误地认为任务是数据处理逻辑失败。另外，所有文件路径都通过参数传入，不允许脚本读取环境变量来猜路径。Agent 是严格按照 SKILL.md 的说明来执行命令的，如果命令参数不确定，它会犹豫甚至自行脑补，脑补的后果等于脚本的行为不可复现。

对于复杂的技能，我还会在技能目录里单独维护一个requirements.txt，并在 SKILL.md 的依赖小节里注明安装命令。现在很多技能库还支持requirements.txt中指定额外的 pip 索引源，这一点对内部环境特别有用。团队里的新成员复制技能库时，一条命令就能把环境搭好，而不是逐个问老员工“你那儿怎么跑通的”。

3.4 技能的回归测试与版本管理：把它当代码对待

很多人会觉得技能不就是一个给模型看的文档和几个脚本，没必要做测试，这个想法迟早会让你栽跟头。我曾经有一次只是改了一个技能描述里示例路径写法，脚本一行没动，结果在真实 Agent 任务里，模型按新描述传了一个不存在的输出目录，任务反复报错。就是因为描述和脚本行为没有做同步验证，一个小小的不一致，让 Agent 完全误解了脚本的预期行为。

所以我后来强制规定：每个技能都有一组固定样例输入和对应的 expected outputs，任何修改，无论改的是脚本还是文档，都必须重新跑一遍这组测试。测试不用做得很复杂，一个简单的测试目录加一个检查脚本就够了。我用的就是基础的 pytest，每个技能对应一个测试用例，验证输入、执行、输出、退出码四个环节。设定越简单越不容易被绕过，你要设计成每次都要敲长命令，保证你坚持不了一周。

版本管理方面，技能库的每次变更使用语义化版本号，技能本身用目录名固化路径，但允许在 frontmatter 里标注版本。技能发布到仓库后，不能再随便原地修改线上版本，而是要发布新版本目录。原因是 Agent 的缓存机制很可能会导致旧版本 SKILL.md 还留在上下文中，假如你原地修改，它执行时会发生新旧行为混合，排错极其困难。

4. Agent 如何找到并调用技能：自动发现机制与描述工程

4.1 一个经常被忽略的假设：模型真的会看你的技能库吗

很多人在本地搭好技能库，跑通 demo 之后就以为万事大吉了，但实际他们忽略了一个根本假设：Agent 不会天然知道你技能库里有什么。在主流 Agent 框架的实现里，启动时系统会读取技能库清单，并把技能列表交给一个技能选择机制。这个机制可能是模型本身，也可能是一个单独的技能评分模型，但不管具体实现是什么，它依赖的核心信息都只有一个：技能描述与用户当前目标的语义相关度。

这句话翻译成大白话就是：你的 Agent 在做技能选择的一瞬间，拿到的不是完整的 SKILL.md 全部内容，而是每个技能的“标题加描述”这样一个迷你摘要。如果技能描述本身写得像产品新闻稿，没有任何可触发的场景词，那模型根本不会在正确时机想起这个技能。这不是模型能力不够，而是你提供给它的检索信息质量不够。

这也解释了为什么我反复强调描述工程的重要性。你不能把技能库想象成一个“带目录的百科全书”，而要把它想象成一个“面向检索的搜索引擎索引”。Index 里的每一条内容，都要为被准确命中而写作。

4.2 把描述写成触发条件：一个真实的命中率对比

我手里有一个项目，开发了两个技能，一个是把文字笔记转成清单，另一个是从会议纪要里提取行动项。最初的 description 写得很“正规”，类似“A note conversion tool”和“An action item extraction utility”。实测结果，Agent 经常在用户只是随便写一段想法的时候，直接触发了笔记转换技能，因为它看到“note”这个词就觉得命中。而会议纪要提取技能，反而在用户明确要求“从纪要里拉出待办”时犹豫不决。

后来我把两个技能的描述全部重写了一遍。笔记转换技能改成：“当用户明确要求将笔记内容整理成有序清单、待办事项或步骤列表时使用；若用户只是在记录想法、写草稿，没有提出整理要求，绝对不要使用。”会议纪要技能改成：“当用户提供会议记录、访谈稿或多人对话文本，并要求提取可执行的行动项、负责人与截止日期时使用；若用户只是要求概括要点，不要使用。”

改了描述之后，触发精准度提升非常明显。道理其实不复杂：模型做技能选择时，更像一个快速的分类判断，而不是深度阅读。它在有限上下文里看到描述中的“明确要求”和“绝对不要”，会显著降低误触发的概率。给技能写描述，类似在仓库每个箱子上贴标签，标签上必须写清楚里面有什么、什么时候来取，而不是写“优质好物”这种空话。

4.3 元技能：把细粒度技能编排成完整工作流

基础技能越拆越细，Agent 在复杂任务里反而会懵。今天让它生成月度报告，它要自己去想应该先调用清洗技能，再调用指标计算技能，最后调用模板渲染技能。这个过程让模型自由发挥也行，但每次都发挥得不一样，输出风格很不稳定。解决方案就是用元技能（Meta Skill）做编排。

元技能本身也是一个 SKILL.md，只是它不执行任何脚本，它的正文是给 Agent 的流程指令。我最常用的元技能写法，是用编号任务清单描述完整流水线，不用任何图表，就清清楚楚列步骤。比如一个做月度销售简报的元技能，正文是这样：

1. 第一步：调用parse-sales-data技能，把原始销售表转换为统一字段的中间数据文件。
2. 第二步：调用extract-trends技能，基于中间数据计算同比、环比并输出要点摘要。
3. 第三步：调用render-docx-report技能，将摘要和图表渲染为可阅读的月度报告。

元技能让基础技能可以设计得更加“笨”和单一，不必考虑与其他技能的组合关系，只需要把单一职责做到极致。模型在执行元技能时，像项目经理一样按清单调度各个基础技能，每一步之间传递文件，任务边界清晰，任何一步失败都可以精确回溯到具体技能，而不是怪罪“模型理解不对”。我强烈建议技能库超过十个之后，就开始设计元技能层，这是让技能体系真正能支撑复杂业务的关键一环。

5. 上线之后常见的三个故障：我踩过的真实坑和处理记录

5.1 技能明明加载了，Agent 却“装看不见”

技能库第一次试点上线时，我确认系统日志里已经把所有技能文件读取成功，技能列表也出现在上下文中。然而真实对话里，Agent 几乎一个技能都不用，所有任务都靠自己的记忆直接回答。排查了很久，最后发现原因让我哭笑不得：技能描述里写的是“你可以使用此技能”，而系统提示词里没有引导模型优先考虑技能。对模型来说，“可以”代表可选项，不强制，一旦任务路径稍微有点复杂，它就直接跳过技能，凭已有的知识泛化回答。

解决办法是在系统提示词里加了一条优先级规则：当任务与已加载技能匹配时，默认按技能流程执行，而不是直接给用户结论；同时要求模型在输出中标记技能调用痕迹。这个改动之后，技能使用率立刻上来了。这个细节非常关键，尤其是从 Demo 到上线的阶段，很多人跑通但翻车，原因就出在这里。你可以理解为：给模型一个工具箱放在它旁边，它可能懒得用；你得告诉它二选一命题——要么开箱取工具，要么给出不用工具的理由。

5.2 技能描述互相打架：选择漂移的典型表现

技能数量超过 15 个以后，我开始遇到一个新的问题：多个技能描述越来越接近。比如既有extract-tables-from-pdf，又有convert-pdf-to-docx，当用户说“帮我处理一下这个 PDF”，模型会在两个技能之间犹豫，甚至随机挑一个，输出结果当然不稳定。

解决这个问题我没有用复杂算法，而是从流程上做限制：每新增一个技能之前，先全文搜索现有技能库，确认没有描述重叠。如果新技能是一个旧技能的扩展，我就拆掉旧的，升级成一个元技能来覆盖完整流程；如果两个技能确实功能不同，但描述容易混淆，我就必须在双方的 description 里显式加上对照说明。例如在extract-tables-from-pdf的描述里加一句“如果用户需要保留 PDF 的排版并转成 Word 文档，请改用 convert-pdf-to-docx 技能”，反向也写一条。让模型在选择时能够通过排除法锁定正确目标。

5.3 本地能跑，沙箱里就是跑不通：环境不一致问题

技能里的脚本经常出现一个窘境：本地运行一切正常，交给 Agent 的沙箱环境后开始莫名失败。我第一次排查时花了大半个小时，最后发现脚本默认使用系统的 Python，而沙箱里的 Python 路径不同，几个依赖包也没有安装。这个坑特别隐蔽，因为脚本在本地环境下根本不会暴露路径和依赖问题。

后来我把所有技能脚本统一改成在入口处做两件事：第一，显式检查关键依赖是否可用，不可用则立即输出状态码并退出；第二，脚本中用相对路径或者由外部传入绝对路径定位文件和资源，绝不依赖进程当前工作目录。因为 Agent 调用技能时并不保证工作目录是你的技能目录，脚本如果写死了相对路径，一定会在某个环境里崩掉。把环境差异前置到可以排查的状态，故障定位时间直接从半小时级别降到了几分钟。

5.4 技能与 MCP 工具的边界约定

最后再提一个架构层面的坑。如果你的 Agent 既挂了 MCP 服务器，又配了技能库，两者之间一定要有优先级约定。MCP 工具提供的是稳定、可连接的 API 能力，适合做实时数据获取和外部服务调用；技能则更适合模型引导的流程处理和格式转换。假如你在技能里也写了一遍数据库查询逻辑，而这个查询 MCP 工具已经能实现，模型就会面临两个入口，选择时极易混乱。

我对两个体系做了事权划分：一切能通过 MCP 低成本拿到的外部数据和接口能力，都交给 MCP；技能专注在流程编排、格式转换、数据清洗、文档渲染这种需要理解上下文的环节。技能里出现外部系统调用逻辑时，优先写作“调用 MCP 工具xx获取数据”，而不是自己重新写一份接入代码。这样划分以后，模型既不会重复造轮子，也不会因为两套工具语义冲突而选择困难。

按我这几个月的折腾经验，做 Agent 技能体系最关键的一点，是把“技能”当作项目里的一等公民来对待，有目录、有文档、有测试、有版本，而不是简单地把几段 prompt 存成文件。技能写得越清晰，Agent 的表现就越稳定，团队维护起来也越省心。最后分享一个小技巧：技能库根目录维护一个 INDEX.md，把全部技能的名称、用途、所属元技能列成一张总表，让模型在开始检索之前先获得全局视角，能够显著降低误选率。如果你也在搭自己的 agent-skills，希望这篇能帮你少走几步弯路。