企业官网建设流程全解析

做Agent开发最头疼的事，就是prompt越写越长、逻辑越堆越乱，最后整个系统变成一团只有自己能看懂的"咒语"。我最近在做一个复杂任务自动化的项目，发现单纯靠调prompt已经撑不住了，于是把智能体的能力拆成一个个可单独封装、测试、复用的技能包，这套体系就是标题里写的agent-skills。这篇文章就把我整个设计和落地的过程掰开揉碎讲清楚，从为什么要做技能化、skill文件长什么样，到怎么执行、怎么调试，全部基于真实项目里的取舍和踩坑，希望对正在做Agent系统或者准备重构的你有参考价值。

1. 先聊为什么非要做skill化：从裸写prompt到技能包

1.1 裸写prompt的困境：一段提示词塞不下所有逻辑

早期做Agent，最常见的方式就是把所有要求堆进system prompt里：告诉模型你是谁、你的任务是什么、有哪些工具、输出格式是什么、遇到异常怎么处理。起步还行，一旦任务变复杂，问题马上暴露。

最典型的翻车现场是：一边要求模型做"意图识别"，一边又要它抽取关键字段，还要它决定调用哪个工具，最后所有指令全都压在一条上下文里。结果模型经常顾此失彼，要么丢字段，要么格式输出不稳定，要么明明该调用工具的时候开始胡说八道。我印象最深的一次，是让Agent做一份销售数据清洗加汇总的任务，因为prompt里同时塞了清洗规则、汇总口径、输出模板和异常处理逻辑，模型处理到一半竟然自己编了几个不存在的字段名出来填进JSON里。

表面看是模型能力不够，实际上是我把太多职责塞进了一个上下文。人干活的时候都知道把大活儿拆成小步骤，Agent也一样——但问题是，模型没有"拆步骤"的自觉，你给它一锅炖它就只能一锅乱炖。

1.2 技能化之后到底解决了什么问题

我后来想明白一件事：开发Agent不能只调prompt，应该像写代码一样做模块化。把"会清洗数据""会生成周报""会调用某个API并解析结果"这些能力各自封装成一个独立的技能包，模型每次只加载需要的那些技能，在技能内部再去看详细的步骤和约束。

这样做下来有四个直接收益：

• 可复用：清洗数据这个技能封装一次，后续任何Agent、任何项目要清洗数据，直接挂载这个skill就行，不用重新写prompt。
• 可测试：每个skill可以单独用测试用例验证，就像单测一样。裸写prompt时你很难单独测"清洗逻辑对不对"，但skill化之后可以。
• 可组合：不同任务本质上是不同技能的排列组合，能在运行时动态决定"这次任务需要哪几个技能"，比每次全量加载聪明得多。
• 可维护：prompt单独改会影响全局，而技能包的修改范围是封闭的，改A技能不会影响B技能。

用代码工程的话说，这就是把一大坨"全能的main函数"拆成许多个"小而专的函数"。模型调度器负责路由分发，每个技能内部自治，整体可控性会上一个台阶。agent-skills这个项目名的核心含义也在这——给Agent配置的，是一套可管理的技能集合，而不是一段不断膨胀的prompt。

1.3 agent-skills在整体系统里扮演的角色

如果你搭过Agent系统，应该熟悉那套典型的架构：模型负责决策，工具（Tools/Function Calling）负责执行具体动作，工作流（Workflow）负责固定流程编排。那agent-skills的位置在哪里？

我的理解是，它介于"模型决策层"和"工具执行层"之间，属于能力调度层。工具是原子操作，比如"调用某API""执行某段SQL"，技能则是一组工具、指令和校验逻辑的组合，它描述的是"怎么完成一件相对完整的子任务"。模型不需要关心技能的底层是怎么一步步调用工具的，它只需要知道"什么时候该触发哪个技能"。

所以agent-skills不是要替代工具系统，而是把工具的使用姿势从"模型临场摸索"变成"模型直接读取说明书"。配合Function Calling使用效果最好：Function让模型知道有哪些原子操作可用，Skill让模型知道这些原子操作怎么组合起来完成一件事。

2. skills系统设计：从schema到执行引擎，四个核心模块

整个系统设计我最纠结的就是一个问题：一个skill到底应该包含什么、由谁定义？是纯文本还是结构化？应该是人为定义，还是让模型自己生成？最终我把架构固定成四块：技能定义模块、技能注册模块、技能调度模块、技能执行模块。下面一个一个拆开讲。

2.1 skill的文件结构与定义方式：一个skill到底长什么样

我参考了业界比较常见的skills定义方式，自己重新设计了一套相对通用的schema。一个完整的skill包在文件系统里是这样的：

skills/ data_cleaning/ SKILL.md rules.yaml scripts/ clean.py examples/ input.json output.json tests/ test_clean.py weekly_report/ SKILL.md rules.yaml ...

SKILL.md是灵魂，给模型看的说明文档，内容包含这个技能是干什么的、什么时候用、什么时候不能用、使用步骤是什么、有哪些注意事项。rules.yaml是结构化元信息，给系统看的，比如技能名称、版本、描述、需要加载哪些工具、需要注入哪些上下文信息。scripts/放实际执行脚本，examples/放输入输出样例，tests/放验证用例。

关键在设计SKILL.md的结构。我写过一个模板，核心几段是：

• 目的（Purpose）：一句话说清这个技能解决什么问题。
• 适用场景（When to use）：明确列出适用条件，越具体越好，方便调度器匹配。
• 不适用场景（When not to use）：同样重要，能避免很多误触发。
• 执行步骤（Steps）：用编号列出操作流程，每个步骤有输入、处理和输出说明。
• 约束与规则（Constraints）：比如"不要猜测缺失字段""输出必须是合法JSON"。
• 示例（Examples）：给一两个典型场景的输入输出对，模型模仿能力很强，有样例质量会提升很多。

注意一点：SKILL.md不是给人看的注释文件，而是要直接被塞进模型的上下文里的。所以它必须写得像"给一个不太聪明但执行力很强的实习生看的工作手册"——清晰、具体、一步一步来，别写一堆模棱两可的废话。

2.2 技能注册与加载：让Agent知道"自己会什么"

技能包只是静态文件，真正让它生效需要先注册进Agent系统。注册阶段要做三件事：

第一，扫描技能目录，读取每个SKILL.md和rules.yaml，拿到技能名称、版本、触发条件等元信息。第二，为技能建立索引，方便后续检索。第三，校验技能定义是否合法，比如脚本是否存在、依赖的工具是否有定义。这个阶段我只保留元信息，不加载完整的技能正文——全量加载太吃token了。

我踩过的第一个坑就是这边：一开始图省事，启动时把所有技能全文都塞进system prompt里。结果技能多了之后，每次请求的token消耗直接翻倍，而且模型注意力被无关技能内容分散，核心任务反而干不好。后来改成按需加载——每次只注入与当前任务相关的技能描述，大幅缓解token压力，同时准确率更高了。

注册完技能之后，还少不了一个"技能激活"环节。系统启动后，会先列一个可用的技能清单给模型看（类似tool list），让模型知道当前环境里有哪些"牌照"，等到具体任务来了再去按需拉取技能正文。这一步和大模型的Function Calling设计思路是一致的：先给你看函数签名，真的调用时再走具体实现。

2.3 技能调度与执行：动态决定这次用哪个技能

技能执行流程我把它拆成五个阶段，顺序如下：

1. 获取任务目标：接收用户请求，提取核心目标，可以是多轮对话的最后一轮，也可以是系统提交流程里传入的任务参数。
2. 技能匹配：在已注册技能列表里，基于技能名称、描述向量、关键词、规则配置，匹配出一个候选技能集合。我实测下来，简单的关键词+描述匹配已经能应付绝大多数场景，没必要每次都用LLM做语义匹配，性能代价太高。
3. 选择与加载：从候选集合里选最优技能，读取SKILL.md全文，注入到当前对话上下文。
4. 执行技能：模型根据技能里的步骤说明，逐步调用工具、处理数据、输出结果。
5. 校验输出：按rules.yaml里定义的输出约束，检查结果格式和必填字段，不合法就回滚或者重新执行一次。

技能调度是整个系统性能的关键——选错技能的结果是什么？是模型认真学习了一本无关的说明书，然后自信地给出一个驴唇不对马嘴的答案。为了把这一步做好，我在rules.yaml里加了一个字段叫match_keywords，人工维护一批触发关键词。比如数据清洗技能就配了"清洗、去重、缺失值、脏数据、标准化"等词，配合描述里的语义匹配一起用，准确率比纯语义匹配高不少。

执行阶段还要考虑状态传递的问题。技能不是完全独立的，前一个技能的输出常常是下一个技能的输入。我在执行上下文（ExecutionContext）里搞了一个共享KV缓存区，每个技能执行完后可以把结构化产物放进这个区，后面的技能按key取用。这个设计很像Unix管道，每个skill做好自己的事，把产物留给下游，大家不用了解彼此实现细节。

2.4 为什么这样设计：选型与取舍的底层逻辑

可能有朋友会问：直接用现成的工作流编排框架不香吗？非要自己搞一套skill逻辑？我的回答是：工作流和skill解决的是两个不同的问题。

工作流适合固定流程，比如"每天早上8点拉数据-生成报表-发邮件"，这个流程十年不变，当然可以用工作流写死。但Agent面对的是开放任务，比如"帮我把这个文件处理一下"——你怎么预先定义一个固定流程？skill的设计目的是为模型提供"应对开放任务"的标准化模块，它不强制流程，而是给模型足够多的材料和脚手架，让模型自己做决策。把skill和工作流结合是正解：工作流负责稳定的主干，skill负责可变的支线。

另外一个关键取舍：skill的定义到底是让模型自己写还是人写？我初期试过全自动方案，让模型自己生成技能的SKILL.md，最后结果非常不可控——模型生成的语言质量虽然不错，但经常写出"幻觉指令"，比如让工具去调用一个根本不存在的能力。后来折中成人写核心流程、模型补充扩展。人工负责定义技能的骨架和边界，模型可以根据具体任务生成细分的执行子步骤，两边结合起来，既有质量保障，又有灵活性。

3. 实操：从零实现一个可用的数据清洗skill

概念讲一堆，不如直接上手做一个。这一节我用"数据清洗"为例子，完整走一遍一个skill从定义到跑通的全过程。选这个例子是因为它足够典型——有工具调用、有规则约束、有输入输出校验，技能化收益非常明显。

3.1 需求边界与输入输出定义

先明确这个技能要干什么：接收一份表格数据（JSON或CSV格式），执行以下几类操作——剔除重复行、删除全空行、填充/标记缺失值、纠正字段类型（比如把数字字符串转成int）、标准化字段名映射（比如把"u_name"映射为"user_name"）。最后输出一份清洗后的结构化数据和一个清洗报告。

边界要想清楚，别什么事都往skill里塞。比如"这里的数据是不是有业务含义上的异常"不是我这个清洗skill该管的，"统计报表怎么生成"也不是。这个技能只管格式和完整性层面的清洗，不要去碰业务逻辑。

输入和输出定义我直接写进rules.yaml：

name: data_cleaning version: 1.0.0 description: 清洗结构化表格数据，处理去重、缺失值、类型纠正、字段映射 match_keywords: ["清洗", "去重", "缺失值", "脏数据", "标准化"] tools_required: ["read_table", "write_table"] output_schema: type: object properties: cleaned_table: { type: array, description: 清洗后的数据行列表 } cleaning_report: { type: object, description: 清洗报告 } required: ["cleaned_table", "cleaning_report"]

3.2 SKILL.md的写法与prompt工程细节

SKILL.md我是这样写的：

# Skill: data_cleaning ## Purpose 对结构化表格数据执行基础清洗操作，使其满足后续处理与入库要求。 ## When to use - 用户提供CSV/JSON/Excel等表格数据 - 用户要求"清洗""去重""填缺失值""标准化格式" - 数据来自多个不同来源，需要统一字段与格式 ## When not to use - 数据已经是规范的结构化格式且用户未提出清洗诉求 - 用户需要在清洗基础上做业务分析或可视化（这是其他技能的工作） ## Steps 1. 读取完表格数据后，先扫描一遍全表结构：字段名、行数、每列非空比例。 2. 做字段映射：如果存在语义相同但命名不同的列，统一命名为目标标准名，映射关系记录到清洗报告中。 3. 处理重复行：完全重复的行直接删除；关键字段重复但其他字段不相同的，标记为疑似重复，在报告里说明。 4. 处理缺失值：数值型列优先用中位数填充；类别型列用模式填充；如果缺失比例超过50%，建议在报告里提示该列是否需要保留。 5. 纠正类型：把"123"这类数字字符串转为int，把"1,234.56"这类千分位字符串去逗号后转float，日期字符串统一为YYYY-MM-DD格式。 6. 输出清洗后数据和清洗报告。 ## Constraints - 不要臆测缺失数据的业务含义，填充只是技术占位 - cleaning_report必须包含每类操作影响的行数详情 - 当发现字段无法自动映射时，保留原始字段名，并在报告中标记为warning

这里每个步骤都用"动作+条件+产出"的结构来写。实际测试中我发现，模型非常擅长按照编号步骤逐步执行，但前提是每个步骤都给了可判定的操作条件——"缺失比例超过50%，就要提示"这种，不带模糊地带。

3.3 工具调用与校验逻辑的实现

SKILL.md是给模型看的"说明书"，而真正动手处理数据的还是工具和脚本。我把清洗逻辑的主要动作放在一个Python脚本里，模型负责"按说明书调用脚本、解释结果"，而不是让模型自己逐行处理大数据，这能避免很多不可控的性能和精度问题。

核心脚本我做了一个这样的封装：

# scripts/clean.py import pandas as pd import json, sys def clean_table(df, config): report = {"removed_duplicates": 0, "filled_missing": {}, "type_corrections": [], "column_mappings": {}, "warnings": []} # 字段映射 mapping = config.get("column_mapping", {}) df = df.rename(columns=mapping) report["column_mappings"] = mapping # 去重 subset = config.get("dedup_on", None) before = len(df) df = df.drop_duplicates(subset=subset) report["removed_duplicates"] = before - len(df) # 缺失值处理 fill_config = config.get("fill_strategy", "median") for col in df.columns: null_count = df[col].isna().sum() if null_count == 0: continue if null_count / len(df) > 0.5: report["warnings"].append(f"column '{col}' missing rate > 50%, consider dropping") continue if fill_config == "median" and df[col].dtype in ["int64", "float64"]: df[col] = df[col].fillna(df[col].median()) report["filled_missing"][col] = int(null_count) elif df[col].dtype == "object": df[col] = df[col].fillna(df[col].mode()[0] if not df[col].mode().empty else "unknown") report["filled_missing"][col] = int(null_count) return df, report

模型不直接执行脚本里的这些逻辑，而是通过一个execute_skill_tool函数去调用脚本，然后把结果拿回来。这个设计有两个好处：一是脚本可以被单测覆盖，二是模型不需要深入了解pandas API，它的职责变成"理解报告、向用户解释、决定下一步"，更贴近大模型的强项。

工具调用在Agent跑起来后长这样，我贴一段简化的伪代码展示实际执行链路：

# 伪代码：Agent环境中执行skill的主流程 def run_skill_in_agent(skill_name, task_input, agent_context): skill_meta = skill_registry.get(skill_name) skill_doc = read_skill_doc(skill_meta["SKILL.md_path"]) agent_context.inject(skill_doc) # 注入SKILL.md agent_context.inject_system_message("现在你将执行data_cleaning技能，请先读取输入数据。") # Agent自行决策调用工具 next_action = "start" while next_action != "finish": response = agent_context.step(next_action) next_action = parse_action(response) # 可能是 call_tool / reply if next_action == "call_tool": tool_name, tool_args = parse_tool_call(response) if tool_name == "execute_skill_tool": result = call_skill_script(skill_meta, task_input, tool_args) agent_context.add_observation(result) else: result = call_normal_tool(tool_name, tool_args) agent_context.add_observation(result) elif next_action == "reply": final_answer = response break validate_output(skill_meta["output_schema"], final_answer) return final_answer

调试时你会看到，模型有时候会跳过某个步骤或者自作主张合并两个步骤，所以我特意在SKILL.md里加了"不要跳过步骤"的提示。实际跑下来，模型还是大概率遵循编号流程的，因为每一步都有可实操的指示——这比写一堆"请认真处理数据"强太多了。

3.4 测试用例与效果验证

技能写完不等于完事，一定要配测试。我给data_cleaning配了四组测试：正常数据清洗、完全没脏数据（应该快速通过并给出零操作的报告）、极端脏数据（比如90%缺失率、所有字段类型都错）、带未知字段的数据（应该触发warning而不是报错）。

测试跑起来效果很明显。最关键的发现是：有SKILL.md加持的模型，在处理"未知字段"时表现是稳定的——它不会尝试删除这些字段，也不会强行映射，而是保留并标warning。没有SKILL的时候，模型经常自作主张把未知字段丢掉。这个差距直接告诉我：技能文档不是摆设，它在实打实地约束模型的输出行为。

这个skill从需求拆解到测试跑通，前后用了大概半天时间。后面我又按同样套路封装了周报生成、自然语言转SQL、网页文本抽取、批量翻译等技能，每个都在2-4小时内搞定，边际成本比裸写prompt低太多了。

4. 避坑经验：我在skills落地过程中踩过的7个坑

这个章节是我最想写的，因为踩过的坑才是真正的财富。每个坑花了不少时间和token，希望你能绕过去。

4.1 问题速查表

4.2 第一个坑：技能描述写得像论文，Agent根本选不对

我第一个封装的技能是"活动策划"，给它的描述写了整整两百多字的业务背景、目标用户、策划原则，结果调度时模型经常把这个技能匹配给"写文章""做表格"的任务，误触发率高得吓人。后来我把描述精简成二十多个字，加上5个触发关键词，误触发率立刻降下来了。

这个教训就是：技能描述不是项目文档，是给调度器看的"标签"。要像写搜索索引摘要一样写技能描述，精准、短小、关键词明确。越长越模糊，模型越没法准确匹配。特别是"When not to use"这个字段，我强烈建议写上，它在实际效果上排除误触发的贡献比"适用场景"还大。

4.3 第二个坑：SKILL.md里塞了太多"组织希望模型知道"的背景知识

早期我有个执念，觉得技能文档信息越全，模型发挥越好。结果有一次给一个数据分析技能写满了公司业务的复杂度说明，模型在处理开放数据时反而变得畏首畏尾，经常在如何分析上过度纠结，输出速度明显变慢。

后来我把SKILL.md和背景知识库分开了。SKILL.md只负责"怎么完成这个技能"，背景业务知识放到另一个专门的上下文里，按任务决定要不要注入。分工明确之后，模型在技能执行上更利索，在业务理解上也不受影响。这个边界感特别重要。

4.4 其他几个坑的补充说明

• 技能命名别太业务化。有个技能我一开始叫"订单金额汇总"，后来发现它本质是"按条件做数值聚合"，改了名字和描述之后，其他项目也能复用了。
• 脚本要写异常处理。模型不会因为你脚本抛异常就停下来反思，它更可能编造一个结果继续跑。所以脚本里对每个可能出错的地方都要包一层try-except，把错误信息结构化地返回给模型。模型看到明确错误信息，才能正确选择重试或跳过。
• 版本管理一定要做。我吃过一次亏：改SKILL.md的时候把一版已经调得很好的prompt覆盖了，还没法回退。后来所有技能都放git里管理，每次修改留commit，出了问题能diff。
• 输出校验要严格。模型输出的JSON经常出现字段名大小写漂移、多出奇怪的嵌套，必须用schema校验。校验失败就回退重试一次，连续失败再报错给用户。

4.5 调试skills的实用工具

围绕skills调试，我建了一套轻量工具链，都是自己写的，开源界也有类似的思路，核心还是帮你快速定位问题。

• 技能回放器：记录每次Agent调用了哪些技能、每个技能往上下文注入了什么内容、模型是怎么一步步决策的。回放器让我能看到问题出在调度层还是执行层，特别好用。
• 匹配打分器：给一个输入，输出每个技能的匹配得分。调试"为什么选错技能"的利器。
• 单测脚本：每个技能目录底下的tests，用pytest跑，快速回归验证。改动SKILL.md之后跑一遍，能在上Agent前发现prompt变更有没有引入新问题。
• token消耗监控器：统计每次请求里技能正文占用多少token。这个数据会让你知道，按需加载到底帮你省了多少钱。

调试里最反直觉的一条经验是：当模型执行一个技能效果很差时，不要急着调prompt，先看看是不是技能匹配错了。匹配错了，后面怎么调都白搭。我至少有一半的"技能效果不好"问题，最后都定位到是调度阶段把不相关的技能加载进来了。

5. 效果评估与演进：怎么判断一套skills体系到底好不好

5.1 评估指标：不只是任务成功率

技能化改造完成后，我给自己定了几个硬指标来做前后对比，直接用数据判断这套体系值不值得。

• 任务成功率：改造前裸prompt模式下大概是71%，引入skills后提升到了89%。提升主要来自固定步骤带来的稳定性提升，传统prompt模式下模型经常漏掉一些隐含步骤。
• token消耗：按需加载和控制注入内容长度之后，每次任务平均消耗降低了约40%，SKILL.md通常只占上下文中很小的一部分，比起把整个技能体系塞进system prompt省得多。
• 平均执行时长：如果只是简单任务，skill的加载和匹配本身会增加一点延迟，但因为出错和重试大幅减少，整体耗时反而降了。
• 跨任务复用度：这是我最看重的指标。我数了一下，6个核心技能里，有4个在至少3个不同的项目里被复用。这个指标说明skill封装抽到了真正通用的能力层，而不是每个项目都在重复造轮子。

5.2 从静态skill到动态技能组合

目前版本还是"每个技能自己管自己"，下一步我想做的是让skill支持动态组合。比如"数据分析"可能由"数据清洗"+"数据可视化"+"得到洞察"组合而成，Agent可以在运行时动态编排这些基础技能，而不是人为预先写死一个"数据分析大技能"。

这个方向我在冥想设计时有几个方案可选：用LLM直接生成工作流编排脚本，或者用预定义的组合模板，也可以让skill之间声明依赖关系自动串联。目前更看好的是"模板+LLM微调"的路子——模板保证稳定性，LLM做灵活插入，防止完全不靠谱的自由发挥。

另一个演进方向是给skill加版本语义化，比如v1.0.0表示大版本变更，v1.1.0表示规则微调，这样多个线上项目可以锁定某个技能版本，避免上游改动影响下游稳定性。和代码依赖一个道理，Agent系统复杂到一定程度，这个问题一定躲不掉。

我个人做agent-skills这套东西最大的体会是：表面看是在写prompt和脚本，其实是在梳理"人怎么把一件复杂事情拆成可执行的步骤"。技能不是越多越好，而是每个技能都要有清晰的边界。把边界画清楚了，Agent自然就稳了。最后补一个小技巧：不要一开始就把全部技能开发完，先挑一个高频任务反复打磨出第一个skill，把整个流程跑通，后续复制起来会快得多。