企业官网建设流程全解析

如果你最近在折腾大模型应用，肯定绕不开一个词：skills。我第一次看到这个命名的时候，下意识觉得又是包装概念，直到在项目里真正用了一轮才发现，这东西确实把工具调用的开发体验改变了不少。它不是什么新框架，也不是新协议，而是一套把"模型能力外接"这件事标准化的思路——把某个具体任务所需要的指令、脚本、参考信息打包成一个可复用的技能单元，模型在需要的时候动态加载、按需调用。

这篇文章就围绕 skills 这个主题，把我实际做过的技能设计、代码实现、踩坑记录全部梳理一遍。适合已经在用大模型 API 做应用的开发者，也适合刚接触 Agent 开发、想搞明白"技能和工具到底差在哪"的朋友。

1. 理解 skills 到底在解决什么问题

1.1 从一段让人头疼的提示词说起

做过 Agent 开发的人都有过这种体验：想让模型执行一个稍微复杂的任务，比如"把会议录音的转写文本整理成格式化的会议纪要"，最朴素的写法就是在系统提示词里塞一大段规则。一开始还好，等业务规则越来越多，提示词动辄几千字，每次请求都要把所有规则重新发给模型，浪费 token 不说，模型还经常把早期规则"忘掉"，尤其是中间穿插了好几轮多轮对话之后。

我见过一个团队的做法更粗暴：把所有工具说明、业务规范、示例模板全部拼进 system prompt，结果上下文窗口被占掉一大半，模型回答质量肉眼可见地下降。这根本不是模型能力问题，而是工程结构问题。skills 的思路正好对症——把不同任务所需的知识和脚本拆成独立模块，模型先读技能清单，确认需要哪个技能再加载对应内容，用多少加载多少。

1.2 Skills、工具调用、模型上下文协议之间的关系

很多朋友第一次接触这三个概念容易混，我用自己的理解说清楚一点。工具调用（Function Calling）是模型输出结构化调用指令的能力底座，它解决的是"模型决定调用哪个函数、传入什么参数"的问题。模型上下文协议（MCP）是工具和数据的传输标准，解决的是"不同客户端怎么统一连上外部工具"的问题。而 skills 更侧重"任务级"的封装——一个技能里可以包含多个工具调用、一段专有的指令模板、一批参考数据，甚至还可以内嵌一套自己的工作流。

打个比方：工具调用相当于给你一把螺丝刀，MCP 相当于统一了螺丝刀的接口标准，而 skills 是一整套"怎么用螺丝刀组装一台柜子"的作业指导书加配套工具箱。螺丝刀你有很多把，真正让你高效干活的，是那个装了指导书和专用工具的盒子。

1.3 一个技能包的典型构成

我实际用下来的经验，一个完整的技能包通常包含三部分。第一是描述文件，用 YAML 或 Markdown 开头写成，里面写名字、用途描述、适用场景、参数定义，这段是给模型看的，决定了模型"要不要用、什么时候用、怎么用"这个技能。第二是执行逻辑，可以是一段脚本、一个命令行程序或者一个 API 调用封装，技能被选中后由它完成实际计算。第三是参考资源，比如模板、示例、分类规则、历史案例，模型在执行时可以读取这些内容来提升输出质量。

这里有一个关键设计：技能不是只给模型看文档，也不是只给程序跑脚本，它是"文档 + 代码 + 数据"三者的组合。模型理解任务、拆解步骤，脚本负责精确计算，数据提供领域知识，各干各的活。后面我会用一个具体例子把这三部分串起来。

2. 技能设计：先想清楚边界，再写代码

2.1 技能粒度怎么定

技能粒度是设计阶段最需要想清楚的问题。定得太粗，一个技能里塞了太多任务类型，模型不知道该调用，描述也不好写。定得太细，技能数量爆炸，模型在清单里选择困难，管理成本也上来了。

我常用的判断标准很简单：一个技能必须能回答三个问题——输入是什么，输出是什么，在什么条件下触发。如果这三个问题里有一个回答得含糊，说明粒度不对。比如"整理文档"这个技能就不合格，因为输入可能是音频、图片、PDF、网页，输出可能是摘要、思维导图、翻译稿，触发条件也不明确。拆成"会议转写整理""PDF合同风险提取""网页文章摘要"三个技能就清楚多了。

这里还牵扯到一个取舍：技能数量不是越少越好，也不是越多越好。以我目前带过的项目来看，二三十个技能以内模型选择基本不会出乱子，超过五十个就要考虑给技能加元标签做分组筛选了。

2.2 描述文件是给模型看的说明书

整个技能包里面，描述文件的优先级最高，但很多人恰恰最不重视。描述写得好不好，直接决定模型调用率。如果你发现模型总是"忘记"用某个技能，九成是描述文件写得不够清楚。

我总结出一套描述文件的写法：开头一句话说清楚技能是干什么的，使用主动语态，动词开头。接下来写适用场景和不适用的场景，尤其要写"不适用"，这能帮模型排除干扰项。然后写参数定义，参数名、类型、取值范围、是否必填，越精确越好。最后写一个使用示例，用一两句话展示什么情况下该调这个技能。

我有个项目里的技能描述初稿写的是"帮助用户整理文件"，模型调用率不到四成。改成"当用户提供多个本地文档或扫描件并要求批量生成摘要时调用本技能。每个文档单独输出一段 200 字以内的中文摘要，不支持图片识别，不支持跨文档对比"之后，调用率直接升到九成以上。"不适用"那几句话功不可没。

2.3 输入输出协议设计要点

输入输出设计上我踩过几次坑，最大的一个是"参数过度设计"。早期做技能的时候总想把所有可能的参数都暴露给模型，结果模型在传参时经常互相矛盾，比如既传了"日期范围"又传了"具体日期"。后来我把参数精简到最少必要集合，能用默认值解决的就不让模型传，参数之间的依赖关系用描述写清楚，问题基本消失。

输出方面要特别注意结构稳定。如果是给下游程序消费，必须规定输出格式为结构化数据，并给出字段说明。如果是给人读的文本，最好提供输出模板，让模型按模板填充而不是自由发挥。技能包里的模板文件这时候就派上用场了。

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

3.1 搭建目录与元信息

拿一个我实际做过的"会议纪要整理"技能举例。它的任务是把一段口语化的会议转写文本，整理成包含"决议、待办、风险"三个模块的结构化纪要。我在项目里把目录建成了这样：

team-skills/ └── meeting-notes/ ├── SKILL.md ├── scripts/ │ └── format_notes.py └── templates/ └── meeting_minutes_template.md

描述文件我通常命名为 SKILL.md，放在技能根目录。开头用 YAML frontmatter 写元信息，下面是正文指令。这是我最常用的一种写法：

--- name: meeting-notes description: 当用户提供会议或讨论的原始转写文本，要求整理成会议纪要时使用。输出包含决议、待办、风险三部分的结构化中文纪要。不适用于录音文件直接转写，不适用于生成翻译稿。 --- 你需要将用户提供的原始转写文本整理为会议纪要。 步骤： 1. 阅读全部转写文本，识别讨论主题和关键人物。 2. 区分内容：已达成一致的结论写入"决议"；明确分配给某人的动作写入"待办"，并标注负责人；可能阻碍进度的内容写入"风险"。 3. 按模板格式输出，不得遗漏任何模块。 注意： - 待办事项必须包含负责人和截止时间，如原文未提及则标记为"未明确"。 - 不得添加原文不存在的业务决策。

这里 YAML 里的 name 和 description 会被系统读取生成技能清单，而正文部分只有在模型选中这个技能后才会被完整加载。这是 skills 和传统提示词工程的一个显著区别：不是所有内容一开始就占用上下文，而是按需加载。

3.2 编写执行逻辑脚本

描述文件负责"让模型知道怎么用"，脚本负责"让结果更可靠"。不是每个技能都需要脚本，但如果你的技能里有计算、格式化、数据转换这类确定性工作，别指望模型自己完成——模型擅长理解和生成，不擅长精确计算和格式控制。

我在"会议纪要整理"技能里加了一个 Python 脚本，专门做待办事项的格式校验和时间归一化。模型生成纪要后，脚本自动检查每个待办是否有负责人和截止时间，顺手把"明天""下周一"这类相对时间转成具体日期：

#!/usr/bin/env python3 import re import sys from datetime import datetime, timedelta def normalize_deadline(text: str) -> str: today = datetime.now().date() if "明天" in text: return (today + timedelta(days=1)).isoformat() if "下周" in text: return (today + timedelta(days=7 - today.weekday() + 7)).isoformat() if "这周" in text: return (today + timedelta(days=5 - today.weekday())).isoformat() return text def check_todo_item(item: dict) -> dict: issues = [] if not item.get("owner"): issues.append("缺少负责人") if not item.get("deadline") or item["deadline"] == "未明确": issues.append("缺少截止时间") if item.get("deadline"): item["deadline"] = normalize_deadline(item["deadline"]) item["issues"] = issues return item if __name__ == "__main__": # 实际项目中这里会读取模型输出的JSON，这里只展示核心逻辑 sample = {"task": "完成架构方案评审", "owner": "", "deadline": "下周五"} print(check_todo_item(sample))

脚本的输出可以作为校验结果回传给模型，模型根据校验结果自行修正。这种做法把"类型化工具调用"和"模型自主修正"结合了起来，比单纯让模型一次性生成终稿稳健得多。

3.3 接入测试：从单测到端到端

技能开发完必须测，而且不是测一次，是持续测。我习惯先做单元测试——用固定的转写文本跑技能，检查输出结构是否完整；再做多样本测试——准备几十条覆盖不同场景的输入，看模型的调用表现和输出质量；最后做回归测试，每次更新描述文件或脚本之后，把历史测试用例全部重跑一遍，防止改一个技能的某个细节导致另一个场景失效。

我在这个环节踩过最大的坑是测试样本太"干净"。真实用户的输入往往夹杂口语、口误、打断、闲聊，和测试时给的条理清晰的转写稿完全两回事。后来我专门收集了一批真实场景的转写片段加入测试集，问题才逐渐暴露并被修复。记住一个原则：测试输入要脏，模型才能变强。

4. 进阶优化与工程化落地

4.1 上下文瘦身：渐进式披露

上文提到技能的核心优势是"按需加载"，实际操作中还能再进一步。一个技能包里的参考文档可能很大，如果模型一选中技能就把所有参考文档全部塞进上下文，性能优势就被抵消了。我的做法是分级披露：技能被选中时，只加载描述文件里的简短指令和索引；模型判断需要更细的规则时，再通过特定格式的指令去读取详细参考文档。

比如在"合同风险提取"技能里，参考文档是一个包含几十类风险条款定义的文件。如果一次性加载，占了大量上下文但可能只用到其中几类。我在描述文件里写了"如遇合同包含知识产权条款，请查阅 references/ip_clauses.md 获取判定规则"，让模型按需去读。实测上下文占用能减少一半以上，响应速度也明显提升。

4.2 权限与沙箱：给你的技能上锁

技能本质上是可执行代码，一旦封装不严，就是安全隐患。我见过有人把技能脚本写成直接调用系统命令，如果模型被提示词注入诱导，后果不堪设想。我建议所有技能脚本运行在受限环境里：只开放必要的文件路径，禁止网络访问除非明确配置，限制执行时间和资源占用。

权限控制也要细化到用户维度。同一个"文件搜索"技能，普通用户版只能搜自己目录下的文件，管理员版才允许搜共享目录。这个逻辑不能在模型层做，必须在技能脚本的入口做校验，因为模型不可控，代码才可控。

4.3 版本管理与团队协作

技能是会持续演进的，没有版本管理必然出事。我的做法是用 Git 管理技能仓库，每个技能独立目录，改动走分支合并。关键的一点是：技能包的 SKILL.md 头部加一行 version 字段，技能清单里也展示版本号，这样当模型输出和预期不符时，能快速定位是不是技能版本变更导致的。

团队协作时最忌讳的是"某人在一个技能里顺手改了另一个技能的东西"。我要求所有修改必须附带变更说明，描述文件里的任何改动都要在 CHANGELOG 里登记。刚开始觉得繁琐，后来一个线上事故全靠变更记录排查出来，才觉得完全值得。

5. 常见问题与排查技巧实录

5.1 技能始终不被调用，怎么办

这是新手最常遇到的问题。排查顺序我建议从三个层面走：先看技能清单里描述是否正常展示，再看描述与用户问题是否真的匹配，最后看技能是否被隐藏或禁用。前两个层面占到九成以上原因。

我处理过一个案例：某同学做的"代码审查"技能，描述里写的是"当用户提交代码并希望检查质量时使用"，结果用户说的是"帮我看看这段代码有什么问题"，模型没调用。原因就是"希望检查质量"和"看看有什么问题"在语义上模型判定不匹配。把描述改成"当用户提供代码片段并询问其缺陷、优化空间或质量问题时使用"后，调用立刻正常。描述文件要多写触发信号，少写抽象概念。

5.2 参数被模型"编造"了

模型在调用技能时编造参数，是另一个高发问题。典型场景是：技能要求传用户 ID，模型没从上下文找到真实 ID，直接捏了一个。解决这个问题不能只靠提示词"不要编造"，要双管齐下：参数校验脚本必须检查每项数据是否有可靠来源，无法确认来源的参数直接拒绝执行；描述文件里明确写"用户 ID 必须从对话上下文中获取，不得自行假设"。

更稳妥的做法是：把可从上下文自动推导的参数做成可选参数，偏向缺省值；把必须由用户明确提供的参数设计为强校验字段。那些编造的参数通常都是模型自以为能从上下文里推断出来的，我们把参数设计得越"难猜"，编造概率就越低。

5.3 输出格式不稳定，下游解析报错

技能输出格式不稳定往往发生在输出是自然语言夹杂结构化数据的时候。模型可能一会儿输出 JSON 一会儿输出 Markdown，一会儿字段名带引号一会儿不带。我的解决方案是两层：描述文件里给出严格的输出格式定义和示例；脚本做后处理时用容错解析，比如提取 Markdown 代码块里的 JSON，或者用正则抓取关键字段。

还有一个"偏方"挺好用：让模型先把内容生成到中间格式，脚本负责转换成最终格式，转换后再校验一次完整性。格式问题在脚本层解决，永远比在模型层解决省力。

5.4 注意技能的边界与安全

最后必须强调安全。技能描述文件里如果包含了敏感业务信息，调用模型读取时也可能泄露风险。技能脚本对外发请求时要审查目标地址，技能日志不要记录敏感字段。我把技能日志分为两级：调试期记录完整入参和出参，上线后只记录技能名、耗时和结果状态。

还有一点很多人忽略：技能清单本身也会暴露业务信息。在面向外部用户的场景，技能清单应该做权限过滤，别让用户看到系统一共注册了哪些技能。这不是多虑，是基本的安全卫生。

最后分享一点个人体会

我在实际项目里用下来的最大感受是：skills 改变了我和模型协作的方式。以前写提示词总觉得是在"教育"模型，把每一条规则都塞进上下文里；现在更像是在给模型"配置能力"，它自己决定什么时候调用什么。这种转变带来的直接收益是长对话场景下的稳定性明显提升，上下文占用下降，维护成本也低了。

如果你正打算把东西技能化，我给一个建议：从一个小而明确的场景开始，拆好描述文件，做好测试集，比一上来做一堆技能有用得多。技能化的本质不是写代码，而是把一件事的边界、输入、输出和判断标准想清楚——想清楚了，代码只是顺水推舟的事。