企业官网建设流程全解析

最近在重构一个智能体项目的时候，我明显感受到一个瓶颈：单靠把提示词写长、把工具函数堆满，Agent 的表现在达到某个阈值之后就再也上不去了——它开始频繁选错工具、把简单任务做复杂、上下文稍微一长就忘了前面的目标。那段时间我一度怀疑是模型能力不够，后来反复调试才发现，问题出在我给 Agent 的"能力单元"组织方式太粗糙了。于是我花了两周时间把整套能力体系改造成以技能（Skill）为单位的架构，也就是这个项目的主角"agent-skills"。

这篇文章想分享的就是我在这套技能化改造里的完整思路和落地过程，包括技能应该如何封装、描述怎么写才容易被 Agent 正确调用、技能注册表如何设计、多技能编排怎么做，以及我实际踩过的几个坑。如果你正在做 Agent 应用开发、接入了大模型但觉得工具调用不稳定，或者单纯对"怎么让 Agent 更可靠"感兴趣，这篇文章应该能给你一些可以直接抄走的方案。

1. 从一行 Prompt 到一套技能体系

1.1 我为什么重新思考 Agent 的"能力单元"

先说个背景。我做的这个项目是一个偏向文本处理和数据整理的智能助手，早期版本里所有能力都靠一个巨大的 System Prompt 来描述。Prompt 里写了它能做什么、不能做什么、遇到某类输入时应该调用哪个函数，整个 Prompt 加起来将近 4000 字。模型是主流的大模型，推理能力不算差，但实际跑起来问题特别多。

最典型的问题是"工具选择漂移"：明明我写清楚了"当用户需要提取日期时调用 extract_date"，可模型有时候会自己去正则匹配，有时候会调用另一个更通用的工具，还有时候直接凭空给答案。后来我做了个统计，发现工具调用准确率只有六成多，相当一部分任务需要人工纠正或者重跑。另一个问题是 Prompt 太长之后，模型对后面内容的注意力明显下降，尤其当对话轮次多了，早期的工具约束基本就失效了。

这事让我意识到一个问题：把能力描述堆在 Prompt 里，本质上是在用"文本记忆"承载"能力索引"，而文本记忆是有容量和衰减的。更好的做法是把能力封装成独立的、自包含的单元，让 Agent 不是"记住"能力，而是"发现"能力，需要用的时候再去读取对应技能的定义。这就是技能化的出发点。

1.2 技能（Skill）与提示词、工具到底有什么区别

很多人的第一反应是：技能不就是把提示词拆开吗？或者技能不就是工具函数的包装吗？我一开始也是这么想的，但实际设计下来发现它们有本质区别，搞清楚这个区别是做好技能体系的前提。

工具（Tool）是面向"执行"的。一个函数、一个 API 接口，输入输出都是结构化的，Agent 需要选择一个工具来调用。工具描述写得再好，也只是在告诉模型"什么时候用我、怎么填参数"。工具本身没有主动性，它不会告诉你任务该怎么拆解，也不会提供中间的推理过程。

提示词（Prompt）是面向"约束"的。它告诉模型遵循什么规则、按什么步骤思考、输出什么格式。但提示词是线性的文本，所有规则平铺在一起，没有层级，也没有条件触发机制。一个 Prompt 写的规则越多，每一条的相对权重就越低。

技能（Skill）则是把两者融合在一起的结构化单元。一个技能至少包含三个层次：触发条件（什么时候该被想起来）、执行方案（具体怎么做，可以是提示词步骤，也可以包含代码调用）、输出约定（结果长什么样）。更关键的是，技能可以嵌套，一个技能内部可以调用其他技能，这样就形成了能力的分层。

我用一个类比来理解：工具是工具箱里的扳手和螺丝刀，提示词是师傅嘴上不停念叨的注意事项，而技能是"一整套换轮胎的操作规程"——它告诉你什么时候该用扳手、什么时候用千斤顶、顺序是什么、每步做到什么程度算合格。Agent 面对任务时，不是在 Prompt 里大海捞针找规则，而是先判断"这属于哪个技能的职责范围"，然后加载这个技能来执行。

2. 技能封装的核心设计原则

2.1 单一职责：一个技能只做一件完整的事

我在设计技能体系时第一个原则就是单一职责，但这个"单一职责"和人说的可能不太一样。不是"只做一个小操作"，而是"完整地解决一类问题"。

举个例子。我最初把"提取日期"作为一个技能，把"计算日期差值"作为另一个技能，还把"格式化日期输出"作为第三个。结果发现 Agent 在遇到"帮我看看这两个日期相差几天"这种真实需求时，需要连续调用三个技能，任何一个环节调用错了，结果就全错了。后来我把它们合并成一个"日期处理"技能，内部包含提取、计算、格式化三个步骤，对外只暴露一个入口：输入是一段文本，输出是一个结构化日期结果。

这个改动的效果很明显。原来三个小技能之间的衔接由 Agent 临场决定，现在衔接逻辑固化在技能内部，Agent 只需要做一次决策：这问题是不是"日期处理"的职责范围。决策次数少了，错的自然就少了。

所以我在设计技能时给自己定了一条标准：如果一个需求场景需要连续调用两个以上技能才能完成，那说明这两个技能本身应该合并成一个更高层级的技能，或者应该设计一个新的组合技能来承接这个场景。技能的单位不是"操作的原子性"，而是"场景的完整性"。

2.2 技能描述的质量直接决定调用率

技能能不能被 Agent 正确调用，七成功劳在描述文件，这个比例是我实测估的，但方向肯定没错。很多人的技能描述写得太"软"，比如"此技能可以用于处理文本"，这种描述在技能数量少的时候还能靠模型猜，技能一多必乱。

我的经验是，技能描述必须包含三个明确的部分。第一是"触发场景"，要用具体的、贴近用户真实表达的语言列出：什么样的问题出现时应该调用这个技能，最好给出三到五个典型例子，用用户可能说的话来写。第二是"能力边界"，清晰说明这个技能不处理什么，避免 Agent 拿它硬套。第三是"关键限制"，比如输入格式要求、最大长度限制、依赖哪些资源。

举个对比。我写过两个版本的描述，效果差很多。第一个版本是："处理文本中的日期信息，提取相关日期。"第二个版本是："当用户提供包含日期表述的文本（如'下周一''2024年3月5号''上个月末'）并要求整理、计算或转换日期时，使用此技能。本技能能够识别绝对日期和相对日期，输出统一为 ISO 8601 格式。如果用户仅要求当前日期而非文本中的日期，请使用当前时间工具而非本技能。"第二版上线后，这个技能的调用准确率从七成提到了九成以上。

描述里的例子不是随便写的，而是从真实用户日志里扒出来的高频表达。我每隔一段时间就会把 Agent 判断失误的 case 翻出来，如果发现某类表达没被触发，就补进描述里。技能描述是在对话中长出来的，不是一次写死的。

2.3 上下文通胀：能省则省

技能体系还有一个常被忽略的问题，就是上下文通胀。如果你的技能是"把技能的全部内容都塞进 System Prompt"，那本质上跟那 4000 字 Prompt 没有区别，甚至更浪费，因为每个技能都带了大量示例和内部文档。

我采用的做法是分层加载：System Prompt 里只保留每个技能的"索引卡片"，也就是技能名称加一句话描述加触发标签，总共几十个字，技能数量再多也能控制在合理范围内。完整的技能定义（包括详细步骤、代码片段、示例）放在外部存储里，当 Agent 判断"这个任务需要调用某技能"时，通过一个加载函数把完整定义注入当前上下文。

这个机制让我把 System Prompt 从原来的 4000 字降到了 600 字左右，而技能库可以无限扩展，不用再担心"技能太多导致模型看不过来"。这也算是技能体系对比传统 Prompt 工程最大的优势之一：能力可以无限增加，但模型每次只需要关注它当下关心的那一小部分。

3. 从零实现一个可复用的 Agent 技能

3.1 技能目录与项目结构

技能不能散落成一堆文件，否则维护起来就是灾难。我采用的是标准化的技能目录，一个技能一个文件夹，里面固定几个文件。这个结构参考了市面上几种主流 Agent 技能框架的约定，然后根据我自己的使用习惯做了调整。

每个技能文件夹里至少有四个文件：SKILL.md是给人看也给 Agent 看的说明文件，包含技能的所有元信息和执行说明；main.py是技能的核心逻辑，提供可调用的入口函数；requirements.txt声明这个技能需要的 Python 依赖；assets/目录存放技能相关的模板、词典或者辅助数据。如果技能需要额外的配置，就放一个config.yaml。

我把所有技能放在skills/目录下，每个子目录用短横线命名，比如skills/date-processor/、skills/text-summarizer/。目录结构本身要包含技能 ID，方便程序扫描注册。下面是我项目的实际结构，简化了一下：

agent-skills/ ├── skills/ │ ├── date-processor/ │ │ ├── SKILL.md │ │ ├── main.py │ │ ├── requirements.txt │ │ └── assets/ │ │ └── date_patterns.json │ ├── text-summarizer/ │ │ ├── SKILL.md │ │ ├── main.py │ │ └── requirements.txt │ └── table-cleaner/ │ ├── SKILL.md │ ├── main.py │ └── config.yaml ├── registry.py ├── loader.py └── app.py

这样的好处是所有技能都长一个样子，新增一个技能就是复制一个模板目录改内容，不需要重新设计接入逻辑。扫描器直接遍历skills/下的子目录，读取每个目录里的SKILL.md第一段元信息，就能构建出技能注册表。

3.2 SKILL.md 的元信息与执行说明怎么写

SKILL.md是整个技能的灵魂文件，既要给 Agent 看，也要给开发维护的人看。我把它分成两段：第一段是 YAML 格式的元信息，第二段是 Markdown 格式的执行说明。元信息部分我用标准字段：name是技能标识，description是给 Agent 看的完整描述，tags是触发标签，version是版本号，dependencies是依赖的技能 ID 列表。

执行说明部分我要求必须包含三个小节：When to use、How to use、Output format。这三个小节对应我前面说的触发条件、执行方案、输出约定。这里的关键是执行说明要用"给 Agent 看的语气"来写，而不是"给程序员看的文档"。给程序员看你会写"函数接受一个字符串参数并返回字典"，给 Agent 看应该写"首先提取文本中所有绝对日期，然后对每个日期执行归一化，最后按指定格式返回结果"。

下面是我做的一个示例技能的SKILL.md，功能是从文本中提取并标准化日期。这个技能不算复杂，但足够说明格式：

--- name: date-processor description: >- 当用户提供包含日期表述的文本（如"下周一""2024年3月5号""上个月末" "后天下午三点"）并要求提取、计算、转换或比较日期时，使用此技能。 本技能支持绝对日期与相对日期解析，输出统一为 ISO 8601 格式。 如果用户仅询问"今天是什么日期"，请使用当前时间工具，而非本技能。 tags: [date, time, 日期, 时间, 日程] version: 1.2.0 dependencies: [] --- # Date Processor Skill ## When to use - 用户给出包含日期的文本并要求"提取所有日期" - 用户要求把自然语言日期转换为指定格式 - 用户询问两个日期之间的间隔天数 - 用户需要把"下周三"这类相对日期换算成具体日期 ## How to use 1. 从输入文本中识别所有日期表述片段，包括绝对日期、相对日期、模糊日期。 2. 使用 `parse_dates(text)` 解析，得到标准日期对象列表。 3. 如果用户需要计算差值，调用 `days_between(d1, d2)`。 4. 如果用户需要格式化输出，调用 `format_dates(dates, fmt="iso")`。 ## Output format 返回 JSON 对象： { "dates": ["2025-01-15", "2025-01-22"], "relative": true, "normalized_text": "..." }

写SKILL.md的时候有一个容易犯的错：把执行说明写成了代码注释。Agent 阅读说明的路径和我阅读说明的路径不同，它对"第一步做什么、第二步做什么"这种过程性描述更敏感。我会刻意用祈使句，并且每个步骤都对应一个具体的函数名，这样模型在生成工具调用时能直接联想到调用目标。

3.3 技能核心逻辑的代码骨架

技能的执行代码我统一定义为一个入口函数，这样加载器可以直接调用。所有技能暴露的入口函数有两个参数：input_data和context。input_data是结构化输入，context是运行时上下文，包括配置、临时目录、其他可用技能的引用。统一函数签名减少了加载器的特殊处理，也让技能的组合嵌套变得容易。

日期处理技能的核心实现如下：

# skills/date-processor/main.py import re import json from datetime import datetime, timedelta from dateutil import parser as date_parser RELATIVE_PATTERNS = { "今天": 0, "明天": 1, "后天": 2, "昨天": -1, "前天": -2, "下周一": lambda d: d + timedelta(days=(7 - d.weekday() + 0) % 7 or 7), } def parse_dates(text: str, reference_date: datetime | None = None) -> list[dict]: """从文本中提取绝对日期和相对日期。""" if reference_date is None: reference_date = datetime.now().date() results = [] iso_pattern = r"\d{4}[-/.]\d{1,2}[-/.]\d{1,2}" for match in re.finditer(iso_pattern, text): try: dt = date_parser.parse(match.group()).date() results.append({"mention": match.group(), "date": dt.isoformat()}) except Exception: continue for phrase, offset in RELATIVE_PATTERNS.items(): if phrase in text: if callable(offset): d = offset(reference_date) else: d = reference_date + timedelta(days=offset) results.append({"mention": phrase, "date": d.isoformat()}) return results def days_between(d1: str, d2: str) -> int: """计算两个 ISO 日期字符串之间的天数差。""" delta = datetime.fromisoformat(d2) - datetime.fromisoformat(d1) return abs(delta.days) def format_dates(dates: list[str], fmt: str = "iso") -> list[str]: """将日期对象格式化为目标格式。""" if fmt == "iso": return dates out = [] for d in dates: dt = datetime.fromisoformat(d) out.append(dt.strftime("%Y年%m月%d日")) # 简化示例 return out def run(input_data: dict, context: dict) -> dict: text = input_data.get("text", "") action = input_data.get("action", "parse") dates = parse_dates(text, context.get("reference_date")) if action == "parse": return {"dates": [d["date"] for d in dates]} if action == "diff" and len(dates) >= 2: d1, d2 = dates[0]["date"], dates[1]["date"] return {"diff_days": days_between(d1, d2)} if action == "format": return {"formatted": format_dates([d["date"] for d in dates])} return {"dates": [d["date"] for d in dates]}

这段代码只覆盖了核心逻辑，但能看出我的设计思路：解析函数是纯函数，不依赖外部状态，便于单元测试；run入口只做调度，根据action分发到不同子功能。我强烈建议把技能的核心逻辑写成纯函数，这样你可以在不启动 Agent 的情况下单独测试它，写起单元测试来也轻松很多。

3.4 技能注册表与加载器的实现

有了技能目录和统一的入口函数，接下来就轮到注册表和加载器。注册表负责扫描目录、读取元信息、建立索引；加载器负责根据技能 ID 动态导入模块并调用。两者合起来就是技能体系的"发现机制"。

我的registry.py实现如下：

# registry.py import yaml from pathlib import Path SKILLS_DIR = Path(__file__).parent / "skills" def scan_skills(): """扫描 skills 目录，返回技能注册表。""" registry = {} for skill_dir in SKILLS_DIR.iterdir(): if not skill_dir.is_dir(): continue md_path = skill_dir / "SKILL.md" if not md_path.exists(): continue with open(md_path, "r", encoding="utf-8") as f: content = f.read() # 提取第一段 YAML front matter if content.startswith("---"): parts = content.split("---", 2) meta = yaml.safe_load(parts[1]) meta["path"] = str(skill_dir) registry[meta["name"]] = meta return registry def build_index_cards(registry): """把每个技能压缩成一行索引卡片，用于注入 System Prompt。""" cards = [] for name, meta in registry.items(): cards.append(f"[{name}] {meta['description']}") return "\n".join(cards)

这里的关键是用 YAML front matter 来做元信息，而不是单独建一个 manifest 文件。好处是技能目录自带说明，开发和维护时打开SKILL.md就能看到全部信息，不需要额外维护映射文件。这个做法是我自己习惯的，如果你的技能数量特别多或者需要和别的系统共享元数据，用独立的 manifest 也可以，看团队协作习惯来定。

加载器loader.py的核心是动态导入：

# loader.py import importlib def load_skill(skill_id: str, skills_dir: str = "skills"): """按技能 ID 加载技能模块，返回其 run 函数。""" mod = importlib.import_module(f"{skills_dir}.{skill_id}.main") return mod.run def execute_skill(skill_id: str, input_data: dict, context: dict): """加载技能并执行，统一异常处理。""" try: run = load_skill(skill_id) return run(input_data, context) except Exception as e: return {"error": str(e), "skill": skill_id}

加载器就这两件事，看起来简单，但它支撑了整个技能体系的扩展性。我后来把技能库从 5 个扩到 25 个，注册表和加载器完全没改过代码，只是新增目录而已。

4. 技能的组合编排与动态调度策略

4.1 让 Agent"先想后做"：技能选择的两阶段策略

技能一多，新的问题就来了：Agent 怎么知道该用哪个？我试过把几十个技能的索引卡片全部塞给模型，让它自己选，结果准确率也就是七成左右。后来我加了一个"路由"阶段，在正式任务处理之前，先让模型输出一个skill_selectionJSON，里面包含它认为需要使用的技能 ID 列表和理由，然后我才按这个列表去执行技能。

这个"先想后做"的策略参考了推理模型的思路。让模型先输出技能选择理由，等于强制它把"任务需要什么能力"和"具体怎么执行"分开思考。实际效果是技能选错率下降了不少。为了把决策成本降下来，我在 System Prompt 里给模型规定了输出格式，让它必须输出严格 JSON，没有商量余地。

一个典型的路由流程如下：

{ "task_type": "date_difference", "skills_needed": ["date-processor"], "reasoning": "用户提供了两个日期表述并要求计算差值，属于日期处理技能职责范围" }

有了这个中间产物，我还能做一件很重要的事：日志分析。每个任务的技能选择理由都被记录下来了，我可以定期分析哪些任务的 reasoning 和最终执行的技能不一致，这些就是技能描述需要优化的地方。这个分析闭环是我技能体系能持续变准的核心原因。

4.2 技能链：组合技能的三种基本模式

任务复杂到一定程度，单个技能就兜不住了。我在实践中总结了三种技能组合模式，基本上覆盖了我遇到的所有场景。

第一种是顺序流水线。A 技能的输出直接作为 B 技能的输入，比如"从文档里提取表格"然后是"清洗表格数据"。这种模式适合数据加工类任务，关键是前一个技能的输出格式必须严格结构化，否则下一个技能接收不到干净的数据。

第二种是分支选择。同一个输入并行调用多个技能，最后合并结果。比如分析一篇文章时，可以同时调摘要技能、关键词提取技能、情感分析技能，最后汇总。这种模式能显著缩短响应时间，但要注意上下文消耗，并行调用的结果如果都很长，合并时得做压缩。

第三种是递归精炼。一个技能的输出不够好，让另一个技能对结果做批判和改进，循环几次。这其实是自反思模式的工程化实现。递归模式效果好，但成本和延迟也高，我一般只在小范围使用，而且会设置最大迭代次数，比如两轮，防止死循环。

# 技能链的一个简单实现 def run_pipeline(skill_chain: list[str], initial_input: dict, context: dict): data = initial_input for skill_id in skill_chain: result = execute_skill(skill_id, data, context) if "error" in result: return {"error": f"skill {skill_id} failed", "detail": result} data = result # 前一个技能的结构化输出作为下一个的输入 return data

技能链的定义不要写在代码里，应该放在配置里，让 Agent 根据任务动态决定需要哪些技能组成链。我通常会让模型输出一个skill_chain数组，然后由执行引擎按顺序跑，这样编排逻辑和技能定义都保持在数据层面，代码不需要因为新任务类型而改版。

4.3 技能版本与隔离：多业务共用时的维护之道

技能库大了之后，版本管理就变得不可回避。我的做法是在技能元信息里带上version字段，注册表扫描时记录当前版本。如果某个技能要改动，我会先在副本上改，测试通过后更新版本号再上线，旧的版本保留在 Git 历史里，随时可以回滚。

多业务共用同一套技能库时还需要考虑隔离。不同业务的提示词偏好不同，输出格式要求不同，不能让技能内部硬编码业务相关的规则。我的方案是技能内部只做通用处理，业务相关的偏好通过context参数传入，让同一技能在不同业务下有不同的表现。比如摘要技能本身不关心你是什么风格，但context里可以传"简洁风格"或"详细风格"，技能内部读这个参数来调节输出。

这就是把"通用能力"和"领域配置"分离，听起来简单，但很多人一开始会图省事把业务规则写死在技能里，导致技能没法复用。等技能数量到了十几个，这种耦合会变成灾难。我吃到这个教训之后，所有技能内部一律不写业务字段，最多读context里的配置项。

5. 实战中踩过的坑与排查速查表

5.1 技能永远不被触发，问题出在描述太"专业"

我最早写的技能描述里有大量开发术语，比如"正则匹配""解析器""AST"，这些词对模型来说太偏了。模型是根据用户意图匹配技能的，用户不会说"请对我的文本执行正则匹配"，他们会说"帮我看看这段话里提到的日期都是几号"。技能描述里的触发场景要用用户的自然语言来写，不是用你的实现术语来写。

排查方法也简单：把真实用户日志里的高频表达提取出来，和技能描述做对比，看有多少表达没有被覆盖。我做过一次统计，发现有个技能的描述只覆盖了真实表达的三分之一，难怪老是不触发。所以我的建议是技能描述写完不要急着上线，先去翻用户历史对话，找到目标需求的所有常见说法，把它们写进触发场景里。

5.2 上下文爆炸，技能内容全部加载了

技能体系最大的优势是上下文节约，但如果不注意，这个优势会被浪费掉。一个典型错误是：为了让 Agent 每次都能选对技能，把每个技能的完整文档都塞进了 System Prompt。几十个技能加一起，光技能描述就有上万字，模型处理时的注意力又被稀释了。

正确做法是用索引卡片做初步路由，当模型选定了具体技能之后，再由加载器注入完整文档。但这个完整文档注入过程也需要控制长度，如果技能文档本身几千字，那加载一个技能就够呛。所以我尽量让SKILL.md的"执行说明"部分压缩在一千字以内，重点是步骤清晰，不要大段举例解释。

5.3 技能执行结果不稳定，忽略了对齐测试

技能代码本身没问题，但 Agent 拿来用的时候，输入参数经常传错。比如日期处理技能需要的是text参数，模型传了个input，结果技能跑起来就报错。这类问题靠调试很难发现，因为模型每次的错法都可能不一样。

我于是建了一个对齐测试集，专门验证技能入口函数的参数兼容性。我把用户典型问题、技能 ID、期望参数写成一个测试表，每次技能描述改动后都跑一遍，确认新描述不会引导模型生成错误的参数。这就像给技能体系加了回归测试，虽然不能完全杜绝参数错误，但大大降低了概率。

5.4 一个容易被忽视的问题：技能内部的脆弱依赖

技能如果依赖某个外部环境变量或者某个路径上存在的文件，上线之后很容易"这边能跑那边跑不了"。比如我有个技能读取本机的一个词典文件，路径写死了，换台机器就崩。问题的根因是技能没有声明自己的依赖边界。

我的解决办法是：所有技能通过requirements.txt声明 Python 依赖，配置文件统一放config.yaml，并规定技能内部不使用绝对路径，所有外部依赖从context里取。这样技能的可移植性就保证了。我把这条规定写进了技能模板的注释里，新写的技能从第一天起就遵守。

5.5 常见问题速查表

6. 技能化改造的效果与后续扩展方向

改造完成后的效果是显而易见的。同样一个跨领域辅助 Agent，工具调用准确率从六成多提升到了九成以上，很多原本需要人工兜底的任务现在能一条链路跑完。更让我满意的是可维护性：以前改 Prompt 要小心翼翼，怕动了这里影响那里，现在改一个技能只要动它自己的目录，其他技能完全不受影响。

我给自己定了一个扩展计划。下一步是先做技能可视化调试台，把每个技能的调用链路、输入输出、耗时全部可视化出来，方便快速定位问题。然后是把技能做成接口形式，让非 Python 技术栈的团队也能复用，比如通过 HTTP 暴露技能调用入口，这样前端或者其他服务也能接入。再长远一点，我希望能让 Agent 在运行中自己发现"现有技能解决不了的问题"，并自动生成新技能的骨架，人工审核后入库，实现能力体系的半自动进化。

这最后一件事目前还只是原型阶段的尝试，但我觉得方向是对的。技能体系的价值不只是让 Agent 更听话，而是把"能力"变成了可管理、可复用、可增长的对象，顺着这个方向走下去，Agent 能做的事情会越来越多。