1. 技能设计的核心思路先搞明白 Skills 解决的是什么问题如果你最近在折腾 AI Agent 或者大模型应用开发大概率会在各种技术社区看到 Skills 这个高频词。刚开始接触的时候我也很懵因为这个词在不同语境下含义完全不一样——有人说的是让大模型调用外部工具的能力有人说的是类似知识库提示词优化那套玩法还有人干脆把它等同于常见的 function calling 封装。先说结论我这里聊的 Skills指的是给 AI 助手或 Agent 预设的、可复用的专项能力模块。它本质上是一套“定义好的行为模式 配套的脚本或工具 精准的触发条件”让模型在遇到特定任务时不再自由发挥而是走一条我们预先验证过的高效路径。我为什么愿意花时间深挖这个方向因为在实际项目里大模型原生的通用能力远不足以支撑生产级应用。举个真实例子让模型直接“写一个定时任务脚本”和让模型调用你封装好的“安全创建定时任务的 Skill”跑出来的结果天差地别。前者可能给出一个逻辑漏洞百出的方案后者则能稳定输出符合你系统约束、路径规范、权限要求的成品。这就是技能化的价值——把不确定性压缩到最低把重复性经验沉淀为产品能力。这类方案适合谁来参考如果你正在做 Agent 类应用、智能客服、自动化工作流编排或者你想让大模型在特定垂直场景里稳定输出高质量结果这篇文章的内容基本就是为你准备的。哪怕你是初学者只要能跟着把第一个技能跑通对整个 Agent 工程化的理解都会上升一个台阶。2. 认知升级从“提示词”到“技能封装”的三层进阶在动手写第一个技能之前我觉得有必要先把底层认知理清楚。因为很多人在这一块吃过亏——以为技能就是写个长提示词结果做出来的东西换个场景就失灵根本原因就是没理解技能和提示词的本质差异。2.1 提示词、工具调用、技能三者到底有什么区别我用一个接近日常生活的例子来解释。假设你开了一家小餐馆提示词是“菜谱”它告诉厨师模型这道菜大概怎么做但厨师仍然需要自己判断火候、咸淡结果经常不稳定。工具调用Function Calling像是“买了台冰箱”它扩展了厨房的存储能力但冰箱不会告诉厨师今天该做什么菜只是一个被动的资源。Skills技能则是“一套标准化的出餐流程”从顾客点单到出餐谁负责切菜、谁负责掌勺、每道菜的标准克重和烹饪时间都定义好了厨师只需要严格照做出品就稳定一致。落到技术上就更好理解了。提示词只是文本输入靠模型的理解能力去执行没有确定性保证工具调用是模型决定何时调用外部函数但参数填什么、如何校验结果模型说了算而技能则是一整套“打包好的解决方案”它包含触发条件、执行步骤、脚本逻辑、输出格式、异常处理模型只是入口真正的核心逻辑写死在技能内部。2.2 为什么单靠提示词撑不起复杂场景我之前接过一个项目要做文档自动分类系统。第一版就是纯提示词方案在提示词里写清楚“请将文档分为合同、发票、报告、其他四类并输出 JSON 格式”。测试的时候准率大概 85%看着还行但一上线就崩了文档里只要出现“合同”两个字无论内容是不是合同模型都会分类为合同。模型输出的 JSON 字段偶尔多一个空格或者字段名变了下游程序直接报错。用户传进来的是 PDF 扫描件模型根本读不到文字整个链路失败。这类问题不是简单调整提示词就能解决的。因为提示词受限于模型的语义理解能力它没有“检查文件扩展名”“调用 OCR 识别”“校验输出 Schema”这些确定性手段。而技能化方案可以针对这些问题逐一设计对策先用文档类型检测脚本做初步筛选再用 OCR 兜底最后强制走 JSON Schema 校验。每一环都是确定的、可测试的整体可靠性自然远高于裸提示词。2.3 技能化方案的三个核心优势第一个优势是可测试性。提示词的输出是概率性的你不好写自动化测试去断言“模型一定输出正确”。技能则可以把核心逻辑拆出来做单元测试比如技能里的脚本可以单独跑、单独验证模型只负责触发和传递参数。第二个优势是可复用性。一个写好的技能可以直接从一个项目搬到另一个项目或者在不同 Agent 之间共享。我之前做了一个“URL 内容安全提取”的技能后来多个项目都在用相当于一份经验多处受益。第三个优势是可维护性。提示词一长后期改起来牵一发动全身而且模型行为不可预期。技能的维护则是模块化的——改脚本就改脚本改描述就改描述哪里出问题点哪里排查效率完全不是一个量级。3. 技能设计的方法论一套反复打磨过的“五步法”了解了概念差异之后接下来就是实操层面的核心问题一个高质量技能到底该怎么设计下面这套方法论是我做了十几个技能之后总结出来的不一定是最优解但至少能帮你避开大部分坑。3.1 第一步明确意图边界别让技能变成“万金油”这是设计阶段最重要的一步。很多初学者喜欢把技能定义得特别宽泛比如“处理用户请求”“数据分析”这种结果模型根本不知道该什么时候触发这个技能触发后也不知道该做哪一步。我常用的方法是为每个技能写一句意图声明如果这句话里出现超过两个“或者”说明技能边界过宽要拆。举个例子不好的意图声明“当用户需要获取网页内容或下载文件或解析数据时触发。”好的意图声明“仅当用户明确要求获取某个页面的正文文本时触发忽略其他操作。”后者对模型而言是清晰的信号。技能命名也要精准我倾向用动词开头的短语例如fetch_page_content、check_domain_reputation而不是 vague 的web_tools或者utils。3.2 第二步定义输入输出契约用参数约束代替模型自由发挥技能的输入输出你就是它的“API 契约”。这部分涉及的细节很多但核心原则就一条严格化输入结构化输出。输入侧你要定义清楚技能接收哪些参数、每个参数的类型、是否必填、取值范围。比如fetch_page_content需要接收 URL那么 URL 的格式校验就应该写在技能里而不是指望模型传一个规范参数进来。实操中我发现一个高频翻车点模型会根据用户自然语言里的表述来填参数比如用户说“帮我看看那个页面”模型可能会传一个约等于没传的模糊描述。对策是在技能里做参数规整——如果参数缺失不执行直接返回“缺少必要参数URL”并且用固定格式提示模型补充。输出侧务必制定一个稳定的结果结构。我自己的习惯是统一用 JSON 包裹结果至少包含三个字段字段名类型说明statusstringsuccess或error整体执行状态resultobject/array/string核心业务结果类型随技能而定error_messagestring/null出错时返回具体原因成功时为null这个结构的好处是后续无论接入日志系统还是做结果解析逻辑都不用变所见即所得。3.3 第三步描述词不是写给用户看的是写给模型看的技能的描述description决定了模型什么时候应该调用它。这个描述的质量直接决定了技能被正确触发的概率。写描述时我给自己定了三条铁律第一包含触发场景的正面示例。比如“当用户提到‘查一下某某网站的内容’、‘把这个网页存成 Markdown’时使用此技能。”第二包含不该触发的反面示例。比如“仅限于获取网页正文不要用于搜索引擎检索、翻译或下载附件。”第三明确参数占位规则。描述里要清楚写明模型需要从用户对话中提取哪些信息作为参数例如“从用户指令中提取完整 URL 作为url参数若缺少该参数诚实告知用户需要提供链接地址。”这里有个我早期踩过的坑描述写得太文学化结果模型把“网页”理解成了包括 PDF、图片在内的所有网络资源。技能被滥用了无数次日志一看全是无效调用。后来我把边界条件在描述里用“仅当”“不包括”“如果是……请勿调用”这类强约束短语钉死误触发率才降下来。3.4 第四步设计执行链条把经验和决策写死在技能里技能内部真正厉害的地方在于你可以把人类的经验和决策规则写进去让模型不再从零推理。比如做一个“判断网站可用性”的技能内部执行链条可以是接收 URL 参数先做基本格式校验用脚本判断协议头是否合法域名是否包含非法字符。尝试建立连接设置 10 秒超时捕获超时异常。如果请求失败做一轮自动重试重试间隔 2 秒最多三次。记录请求耗时、HTTP 状态码、响应体大小。将所有数据整合为 JSON 输出。这条逻辑链完全可以在脚本里硬编码模型只负责传一个 URL 参数。相比把这一整套流程要求写进提示词让模型“理解并执行”技能化方案的稳定性和可观测性完全是碾压级的。3.5 第五步给技能配备“逃生舱”——兜底与降级策略没有不出错的技能所以设计阶段就要想好出错了怎么补救。我通常在技能里预埋三种降级路径第一种是参数缺省降级。如果模型传进来的参数不完整技能本身要有自动补全能力。比如缺 URL 协议头自动补https://缺必要信息返回结构化缺失提示让模型去追问用户。第二种是解析失败降级。比如网页内容抓取后用 BeautifulSoup 解析失败自动切换到正则提取关键字段的模式。能提取多少算多少实在不行再报错把完整响应体丢给模型兜底。第三种是最终保底策略。技能报错时返回的错误信息要设计成“模型可读且可行动”的格式。比如不返回“ERROR 500”而是返回“任务失败目标网站返回403可能的原因是访问被拒绝请尝试排除该细化政策或建议用户更换链接。”这种信息模型看到后能够直接生成对用户有价值的回复。4. 从零实现一个技能以“安全网页内容抓取”为例方法论说完了接下来进入真正的工程实践。我会从建目录到测试全流程走一遍你就明白一个技能到底长什么样、怎么落地。4.1 装好“厨房”技能目录结构与依赖准备一个标准的技能目录我建议至少包含这些模块skills/ └── fetch_and_read_url/ ├── SKILL.md # 技能的“说明书”模型靠它理解技能 ├── script/ │ ├── main.py # 核心执行脚本 │ ├── requirements.txt │ └── utils.py # 辅助函数 ├── tests/ │ ├── test_main.py │ └── fixtures/ # 测试用的数据样本 └── assets/ # 可选放静态资源或配置模板SKILL.md是灵魂文件。它的格式虽然各平台有差异但核心要素是一样的技能名称、意图描述、参数定义、执行说明、输出格式。我一般用 YAML front matter 写元信息正文用 Markdown 写说明。推荐用 UTF-8 编码保存别用什么带 BOM 头的格式否则在 Linux 服务器上解析容易出诡异问题。依赖方面以 Python 为例核心库就是requests、beautifulsoup4、urllib.parse。这里有个小建议尽量少引入重型依赖。我之前在技能里硬塞了pandas结果每次触发技能光加载库就要两三秒体感极差。轻量脚本裁掉所有不必要的库加载速度能快一半以上。4.2 编写 SKILL.md让模型一眼看懂永不错用下面是一个简化但完整的SKILL.md示例。我特别留意了措辞因为前面说过描述决定触发率。--- name: fetch_and_read_url description: 当用户需要查看某个网页的正文内容、提取链接列表或保存页面文案时使用。仅用于抓取和解析网页文本不适用于下载二进制文件、登录后内容或动态渲染页面。 --- # fetch_and_read_url ## 用途 该技能获取给定 URL 的 HTML 内容并提取以下信息 - 页面标题 - 正文文本去除导航、页脚、脚本 - 页面上所有外链a 标签的 href ## 参数 | 参数 | 必填 | 类型 | 说明 | | --- | --- | --- | --- | | url | 是 | string | 目标页面完整地址须包含协议头 | | extract_links | 否 | boolean | 是否提取链接列表默认 false | | max_chars | 否 | int | 正文最多保留的字符数默认 5000最大 20000 | ## 执行说明 1. 对 url 执行格式校验和协议补全。 2. 发起 GET 请求设置超时 15 秒UA 为 Mozilla/5.0 (compatible; SkillBot/1.0)。 3. 使用 BeautifulSoup 解析 HTML移除 script、style、noscript 标签。 4. 提取标题h1/h2 优先其次取 title 标签。 5. 按需求截断正文长度并补齐 JSON 输出。 6. 请求失败时重试最多 2 次间隔 1.5 秒。 ## 输出 始终输出 JSON 对象格式如下 {status: success, result: {title: ..., content: ..., links: []}} 失败时 status 为 error并在 error_message 中说明具体原因。 ## 注意事项 - 如果用户提供的是 PDF、图片或其他非网页文件链接请勿调用本技能。 - 目标地址必须完整含协议头否则返回参数错误信息。 - 抓取内容仅限公开页面不得用于绕过访问控制。这份描述里包含足够多的约束信息模型能在多种任务中准确判断是否调用并在调用时正确填参。写完了建议自己用模型多测几次看看触发率和参数准确率再迭代修饰用词。4.3 核心脚本实现三个关键函数逻辑走向清晰main.py的核心部分我拆成三个函数校验、抓取、解析。这样可以避免所有逻辑堆在一个函数里后面测试也好写。import re import requests from bs4 import BeautifulSoup from urllib.parse import urlparse, urljoin from typing import Dict, List, Optional DEFAULT_UA Mozilla/5.0 (compatible; SkillBot/1.0) TIMEOUT 15 MAX_RETRIES 2 def _validate_url(url: str) - tuple: 校验并规范化 URL。返回 (is_valid, cleaned_url, error_msg) if not url: return False, , url is required if not re.match(r^https?://, url): url https:// url parsed urlparse(url) if not parsed.hostname or . not in parsed.hostname: return False, url, finvalid domain: {parsed.hostname} return True, url, def _fetch_content(url: str) - tuple: 发起请求并抓取 HTML。返回 (html_text, error_msg) headers {User-Agent: DEFAULT_UA} last_error None for attempt in range(MAX_RETRIES 1): try: resp requests.get(url, headersheaders, timeoutTIMEOUT) resp.raise_for_status() return resp.text, except requests.exceptions.Timeout: last_error request timed out except requests.exceptions.HTTPError as e: code e.response.status_code if e.response is not None else unknown last_error fhttp error {code} if code in (401, 403, 404): break # 这些状态重试也没意义 except requests.exceptions.RequestException as e: last_error fnetwork error: {str(e)[:120]} return , last_error def _parse_html(html: str, base_url: str, max_chars: int) - Dict: 解析 HTML提取标题、正文和链接。 soup BeautifulSoup(html, html.parser) for tag in soup([script, style, noscript]): tag.decompose() title h1 soup.find(h1) if h1: title h1.get_text(stripTrue)[:200] else: title_tag soup.find(title) if title_tag: title title_tag.get_text(stripTrue)[:200] content soup.get_text(separator\n, stripTrue) content re.sub(r\n{3,}, \n\n, content) if len(content) max_chars: content content[:max_chars] ... links: List[str] [] for a in soup.find_all(a, hrefTrue): absolute urljoin(base_url, a[href]) if absolute.startswith((http://, https://)) and absolute not in links: links.append(absolute) return {title: title, content: content, links: links}主逻辑没什么花哨的入口函数先校验再抓取最后解析。出错时所有中间过程都会返回可读的错误信息方便模型往下接话。这里有个细节值得留意错误信息要切断不要超出合理长度。第一次写这个技能时网络异常信息我直接str(e)全部输出结果用户看到一坨堆栈模型也不知道怎么处理。现在统一截断到 120 字符一句话说明白原因实际效果好得多。4.4 连接模型接入 Agent 时的触发与返回处理技能写好了怎么接到 Agent 上不管你是用 OpenAI 的 function calling、Anthropic 的 tool use还是自研的 Agent 框架逻辑都差不多在系统提示词或工具列表里声明这个技能让模型知道“有这么个东西可用”。具体接入时我会关注三个点第一工具名对应技能目录描述直接引用SKILL.md中的内容。这本身就是一个动态加载策略建议直接把描述文本塞进 API 请求不用人工精简。第二模型的返回要强约束。比如我要求模型在输出中明确说明“已调用 fetch_and_read_url 技能参数为 xxx”方便做行为审计。凡是模型自己编造的调用记录一律视为 bug。第三外部环境要配合。技能脚本运行时要能够从进程环境变量或请求上下文中读取超时参数。这样在不同的部署环境里技能可以有不同的表现而不用改代码。5. 测试与调试让技能在任何环境下都稳定可用技能写完之后最忌讳的是什么直接上线。我见过太多人写完一个技能测试两三个正常案例就宣布完工结果生产环境一跑各种边角情况全冒出来了。下面这套测试流程是我长年迭代后固定下来的“出厂标准”。5.1 单元测试把核心函数单独拉出来验证对核心脚本我会保证关键函数都有对应的测试用例。以fetch_and_read_url为例测试覆盖面大概是这样测试用例输入场景预期行为URL 缺协议头example.com/page自动补全为https://example.com/page无效域名httpx://abc返回 error错误信息包含invalid domain超时场景连接一个不可达 IP重试 2 次后返回request timed out403 拒绝服务器返回 403不重试返回http error 403内容截断超长页面正文按照max_chars截断并追加省略号外链抽取页面含 5 个链接返回全部链接且去重均为绝对地址测试代码用 pytest 就可以自己本地跑一遍再把测试文件一并提交到仓库。这里有个额外的建议tests/fixtures/里放几个 HTML 样本文件这样测试的时候不用真的发网络请求既快又稳定还能避免测试时被目标网站反爬限制。5.2 集成测试模拟模型调用技能的真实链路单元测试只能验证脚本本身但技能最终是由模型触发的所以集成测试必不可少。我会写一个模拟脚本人为构造一段模型决策逻辑调用技能入口函数传参方式和真实 Agent 完全一致。这样能同时验证两件事第一模型传参格式能不能被技能正确解析。真实场景里模型填参偶尔会多带几个空格或者把布尔值写成字符串true。我在技能入口处统一加了一轮参数规整保证这类情况也能正确处理。第二技能的返回结果是否足够友好。我会刻意构造错误场景传一个 404 链接、传一个空 URL然后看返回的 JSON 能否支撑模型生成一段合理的解释。如果错误信息过于技术化模型容易跟着跑偏这时候就要改错误信息措辞。5.3 回归测试确保迭代不破坏已有功能技能的迭代频率其实挺高的可能过两周就要改一次提示词或脚本逻辑。改完之后跑了全部测试吗这是很多人的盲区。我的习惯是每次改动至少把该技能的所有测试用例跑一遍再跑一遍和它相关联的上下游模块的用例。如果你有 CI 环境把技能测试挂进流水线这就是性价比极高的自动化投入。关于测试我最后想说的一个点测试用例本身也是技能资产的一部分。一个技能换一个人维护如果它有完整的测试集接手成本会降低很多。之前我带团队时发现测试不完整的技能重构时没人敢动最后全变成没人维护的“僵尸技能”。所以哪怕技能简单也建议至少把核心函数的测试补齐。6. 常见问题与排查技巧实录实操过程中遇到的问题好多是第一次碰的时候怎么都想不通、事后才拍大腿的类型。我把自己踩过以及帮别人排查过的典型问题整理出来做成一个速查表希望能帮你节省一些本可以避免的调试时间。现象根本原因快速排查方法解决方案技能从未触发描述词与任务语境不匹配查看调用日志看模型是否在类似场景下选择了其他工具重写 description加入正面和反面示例参数总是缺失模型从用户话术中提取不到信息模拟对话请求打印完整 tool call 请求体描述中补充“缺少参数时必须追问用户”的指令技能执行慢脚本加载了不必要的重型库python -X importtime your_script.py看加载耗时裁剪依赖延迟导入非核心模块输出被下游解析失败返回结构不稳定字段缺失或类型不统一手动跑一次技能用json.loads验证输出在入口处增加合规断言强制 schema多技能互相抢占触发权技能描述之间有重叠场景列出所有技能的意图声明找交集明确优先级重叠场景统一归一个技能处理目标网站限制请求被反爬虫策略拦截查看响应头和状态码区分 403/429调整 UA、降低频率必要时配置代理走正规代理服务6.1 技能“假装触发成功”怎么办这个问题的本质是模型在回复文本里说“已调用技能”但实际上工具调用的请求里根本没有这段调用记录。出现这种情况通常是技能描述里缺少“必须真实发起工具调用”的强约束。我在系统提示词里会专门加一句“未经实际调用不得声称使用过任何工具。若技能调用失败明确告知用户失败原因。”同时在上层的安全日志里做交叉校验凡是无调用记录却声称调用的输出直接打回重放。6.2 模型传参“语义正确但格式全错”怎么办典型场景用户说“帮我看看那个网页”模型识别到用户意图是抓取网页但不知道该传什么 URL 参数于是传了一个空字符串或“那个网页”这样的文本。这种情况下不要指望模型“变聪明”要在技能内部做防御参数缺失时直接返回需要用户澄清的结构化信息。比如fetch_and_read_url的做法是{status: error, error_message: missing_required_parameter: url, result: null}这条错误信息返回到模型那里模型会意识到自己漏了参数从而主动追问用户补齐链接。你会发现这比在提示词里反复强调“你必须提取 URL”奏效得多因为问题被提前拦截在了技能内部。6.3 多技能编排时如何避免冲突当 Agent 挂载了五六个技能之后冲突会发生得很微妙。比如你既有一个“危险域名检测”技能又有一个“URL 内容抓取”技能用户说“看看这个网址安不安全”两个技能描述里都包含“查看网址”这种词模型就容易犯迷糊。我的处理方式是在 SKILL.md 里不只写“做什么”也明确写“不做什么”。例如危险域名检测的描述末尾加上“仅用于域名安全评估不做内容解析若用户需要查看页面内容应选择其他技能。”写完描述之后我会人为构造几个边界测试用例去跑确保哪些技能该触发、哪些不该逻辑清晰。7. 写在最后的经验体会这套技能体系我从最初几个简单脚本折腾到现在最大的感受是技能的边界感和工程质量决定了一个 Agent 项目的天花板。模型的能力固然重要但它只是执行层的一环真正沉淀价值的恰恰是这些看似琐碎、容易被忽视的技能设计与封装。我个人在实际操作中最受益的一个习惯是每个技能上线前都强制自己写一份“一行价值说明”。写不出来就说明技能定位还不够清晰继续打磨。另一个受用的小技巧是技能里的错误日志不记录给用户看而是单独保存一份给开发者看的明细版本问题定位快很多。这些细节单个看不值钱叠在一起就是靠谱和凑合之间的区别。如果你正打算给项目引入技能机制这里建议直接从一个小场景开始先把一个技能的完整链路跑通再逐步扩展到更多场景。技能系统的复杂度会随着数量增长先积累最小可用版本后面再持续丰富、迭代。这个方向后续可做的事还有很多技能的版本管理、技能之间的组合编排、技能的自动发现与推荐每一块都值得单独深挖。希望这篇文章能给你一个足够扎实的起点。
1. 技能设计的核心思路先搞明白 Skills 解决的是什么问题如果你最近在折腾 AI Agent 或者大模型应用开发大概率会在各种技术社区看到 Skills 这个高频词。刚开始接触的时候我也很懵因为这个词在不同语境下含义完全不一样——有人说的是让大模型调用外部工具的能力有人说的是类似知识库提示词优化那套玩法还有人干脆把它等同于常见的 function calling 封装。先说结论我这里聊的 Skills指的是给 AI 助手或 Agent 预设的、可复用的专项能力模块。它本质上是一套“定义好的行为模式 配套的脚本或工具 精准的触发条件”让模型在遇到特定任务时不再自由发挥而是走一条我们预先验证过的高效路径。我为什么愿意花时间深挖这个方向因为在实际项目里大模型原生的通用能力远不足以支撑生产级应用。举个真实例子让模型直接“写一个定时任务脚本”和让模型调用你封装好的“安全创建定时任务的 Skill”跑出来的结果天差地别。前者可能给出一个逻辑漏洞百出的方案后者则能稳定输出符合你系统约束、路径规范、权限要求的成品。这就是技能化的价值——把不确定性压缩到最低把重复性经验沉淀为产品能力。这类方案适合谁来参考如果你正在做 Agent 类应用、智能客服、自动化工作流编排或者你想让大模型在特定垂直场景里稳定输出高质量结果这篇文章的内容基本就是为你准备的。哪怕你是初学者只要能跟着把第一个技能跑通对整个 Agent 工程化的理解都会上升一个台阶。2. 认知升级从“提示词”到“技能封装”的三层进阶在动手写第一个技能之前我觉得有必要先把底层认知理清楚。因为很多人在这一块吃过亏——以为技能就是写个长提示词结果做出来的东西换个场景就失灵根本原因就是没理解技能和提示词的本质差异。2.1 提示词、工具调用、技能三者到底有什么区别我用一个接近日常生活的例子来解释。假设你开了一家小餐馆提示词是“菜谱”它告诉厨师模型这道菜大概怎么做但厨师仍然需要自己判断火候、咸淡结果经常不稳定。工具调用Function Calling像是“买了台冰箱”它扩展了厨房的存储能力但冰箱不会告诉厨师今天该做什么菜只是一个被动的资源。Skills技能则是“一套标准化的出餐流程”从顾客点单到出餐谁负责切菜、谁负责掌勺、每道菜的标准克重和烹饪时间都定义好了厨师只需要严格照做出品就稳定一致。落到技术上就更好理解了。提示词只是文本输入靠模型的理解能力去执行没有确定性保证工具调用是模型决定何时调用外部函数但参数填什么、如何校验结果模型说了算而技能则是一整套“打包好的解决方案”它包含触发条件、执行步骤、脚本逻辑、输出格式、异常处理模型只是入口真正的核心逻辑写死在技能内部。2.2 为什么单靠提示词撑不起复杂场景我之前接过一个项目要做文档自动分类系统。第一版就是纯提示词方案在提示词里写清楚“请将文档分为合同、发票、报告、其他四类并输出 JSON 格式”。测试的时候准率大概 85%看着还行但一上线就崩了文档里只要出现“合同”两个字无论内容是不是合同模型都会分类为合同。模型输出的 JSON 字段偶尔多一个空格或者字段名变了下游程序直接报错。用户传进来的是 PDF 扫描件模型根本读不到文字整个链路失败。这类问题不是简单调整提示词就能解决的。因为提示词受限于模型的语义理解能力它没有“检查文件扩展名”“调用 OCR 识别”“校验输出 Schema”这些确定性手段。而技能化方案可以针对这些问题逐一设计对策先用文档类型检测脚本做初步筛选再用 OCR 兜底最后强制走 JSON Schema 校验。每一环都是确定的、可测试的整体可靠性自然远高于裸提示词。2.3 技能化方案的三个核心优势第一个优势是可测试性。提示词的输出是概率性的你不好写自动化测试去断言“模型一定输出正确”。技能则可以把核心逻辑拆出来做单元测试比如技能里的脚本可以单独跑、单独验证模型只负责触发和传递参数。第二个优势是可复用性。一个写好的技能可以直接从一个项目搬到另一个项目或者在不同 Agent 之间共享。我之前做了一个“URL 内容安全提取”的技能后来多个项目都在用相当于一份经验多处受益。第三个优势是可维护性。提示词一长后期改起来牵一发动全身而且模型行为不可预期。技能的维护则是模块化的——改脚本就改脚本改描述就改描述哪里出问题点哪里排查效率完全不是一个量级。3. 技能设计的方法论一套反复打磨过的“五步法”了解了概念差异之后接下来就是实操层面的核心问题一个高质量技能到底该怎么设计下面这套方法论是我做了十几个技能之后总结出来的不一定是最优解但至少能帮你避开大部分坑。3.1 第一步明确意图边界别让技能变成“万金油”这是设计阶段最重要的一步。很多初学者喜欢把技能定义得特别宽泛比如“处理用户请求”“数据分析”这种结果模型根本不知道该什么时候触发这个技能触发后也不知道该做哪一步。我常用的方法是为每个技能写一句意图声明如果这句话里出现超过两个“或者”说明技能边界过宽要拆。举个例子不好的意图声明“当用户需要获取网页内容或下载文件或解析数据时触发。”好的意图声明“仅当用户明确要求获取某个页面的正文文本时触发忽略其他操作。”后者对模型而言是清晰的信号。技能命名也要精准我倾向用动词开头的短语例如fetch_page_content、check_domain_reputation而不是 vague 的web_tools或者utils。3.2 第二步定义输入输出契约用参数约束代替模型自由发挥技能的输入输出你就是它的“API 契约”。这部分涉及的细节很多但核心原则就一条严格化输入结构化输出。输入侧你要定义清楚技能接收哪些参数、每个参数的类型、是否必填、取值范围。比如fetch_page_content需要接收 URL那么 URL 的格式校验就应该写在技能里而不是指望模型传一个规范参数进来。实操中我发现一个高频翻车点模型会根据用户自然语言里的表述来填参数比如用户说“帮我看看那个页面”模型可能会传一个约等于没传的模糊描述。对策是在技能里做参数规整——如果参数缺失不执行直接返回“缺少必要参数URL”并且用固定格式提示模型补充。输出侧务必制定一个稳定的结果结构。我自己的习惯是统一用 JSON 包裹结果至少包含三个字段字段名类型说明statusstringsuccess或error整体执行状态resultobject/array/string核心业务结果类型随技能而定error_messagestring/null出错时返回具体原因成功时为null这个结构的好处是后续无论接入日志系统还是做结果解析逻辑都不用变所见即所得。3.3 第三步描述词不是写给用户看的是写给模型看的技能的描述description决定了模型什么时候应该调用它。这个描述的质量直接决定了技能被正确触发的概率。写描述时我给自己定了三条铁律第一包含触发场景的正面示例。比如“当用户提到‘查一下某某网站的内容’、‘把这个网页存成 Markdown’时使用此技能。”第二包含不该触发的反面示例。比如“仅限于获取网页正文不要用于搜索引擎检索、翻译或下载附件。”第三明确参数占位规则。描述里要清楚写明模型需要从用户对话中提取哪些信息作为参数例如“从用户指令中提取完整 URL 作为url参数若缺少该参数诚实告知用户需要提供链接地址。”这里有个我早期踩过的坑描述写得太文学化结果模型把“网页”理解成了包括 PDF、图片在内的所有网络资源。技能被滥用了无数次日志一看全是无效调用。后来我把边界条件在描述里用“仅当”“不包括”“如果是……请勿调用”这类强约束短语钉死误触发率才降下来。3.4 第四步设计执行链条把经验和决策写死在技能里技能内部真正厉害的地方在于你可以把人类的经验和决策规则写进去让模型不再从零推理。比如做一个“判断网站可用性”的技能内部执行链条可以是接收 URL 参数先做基本格式校验用脚本判断协议头是否合法域名是否包含非法字符。尝试建立连接设置 10 秒超时捕获超时异常。如果请求失败做一轮自动重试重试间隔 2 秒最多三次。记录请求耗时、HTTP 状态码、响应体大小。将所有数据整合为 JSON 输出。这条逻辑链完全可以在脚本里硬编码模型只负责传一个 URL 参数。相比把这一整套流程要求写进提示词让模型“理解并执行”技能化方案的稳定性和可观测性完全是碾压级的。3.5 第五步给技能配备“逃生舱”——兜底与降级策略没有不出错的技能所以设计阶段就要想好出错了怎么补救。我通常在技能里预埋三种降级路径第一种是参数缺省降级。如果模型传进来的参数不完整技能本身要有自动补全能力。比如缺 URL 协议头自动补https://缺必要信息返回结构化缺失提示让模型去追问用户。第二种是解析失败降级。比如网页内容抓取后用 BeautifulSoup 解析失败自动切换到正则提取关键字段的模式。能提取多少算多少实在不行再报错把完整响应体丢给模型兜底。第三种是最终保底策略。技能报错时返回的错误信息要设计成“模型可读且可行动”的格式。比如不返回“ERROR 500”而是返回“任务失败目标网站返回403可能的原因是访问被拒绝请尝试排除该细化政策或建议用户更换链接。”这种信息模型看到后能够直接生成对用户有价值的回复。4. 从零实现一个技能以“安全网页内容抓取”为例方法论说完了接下来进入真正的工程实践。我会从建目录到测试全流程走一遍你就明白一个技能到底长什么样、怎么落地。4.1 装好“厨房”技能目录结构与依赖准备一个标准的技能目录我建议至少包含这些模块skills/ └── fetch_and_read_url/ ├── SKILL.md # 技能的“说明书”模型靠它理解技能 ├── script/ │ ├── main.py # 核心执行脚本 │ ├── requirements.txt │ └── utils.py # 辅助函数 ├── tests/ │ ├── test_main.py │ └── fixtures/ # 测试用的数据样本 └── assets/ # 可选放静态资源或配置模板SKILL.md是灵魂文件。它的格式虽然各平台有差异但核心要素是一样的技能名称、意图描述、参数定义、执行说明、输出格式。我一般用 YAML front matter 写元信息正文用 Markdown 写说明。推荐用 UTF-8 编码保存别用什么带 BOM 头的格式否则在 Linux 服务器上解析容易出诡异问题。依赖方面以 Python 为例核心库就是requests、beautifulsoup4、urllib.parse。这里有个小建议尽量少引入重型依赖。我之前在技能里硬塞了pandas结果每次触发技能光加载库就要两三秒体感极差。轻量脚本裁掉所有不必要的库加载速度能快一半以上。4.2 编写 SKILL.md让模型一眼看懂永不错用下面是一个简化但完整的SKILL.md示例。我特别留意了措辞因为前面说过描述决定触发率。--- name: fetch_and_read_url description: 当用户需要查看某个网页的正文内容、提取链接列表或保存页面文案时使用。仅用于抓取和解析网页文本不适用于下载二进制文件、登录后内容或动态渲染页面。 --- # fetch_and_read_url ## 用途 该技能获取给定 URL 的 HTML 内容并提取以下信息 - 页面标题 - 正文文本去除导航、页脚、脚本 - 页面上所有外链a 标签的 href ## 参数 | 参数 | 必填 | 类型 | 说明 | | --- | --- | --- | --- | | url | 是 | string | 目标页面完整地址须包含协议头 | | extract_links | 否 | boolean | 是否提取链接列表默认 false | | max_chars | 否 | int | 正文最多保留的字符数默认 5000最大 20000 | ## 执行说明 1. 对 url 执行格式校验和协议补全。 2. 发起 GET 请求设置超时 15 秒UA 为 Mozilla/5.0 (compatible; SkillBot/1.0)。 3. 使用 BeautifulSoup 解析 HTML移除 script、style、noscript 标签。 4. 提取标题h1/h2 优先其次取 title 标签。 5. 按需求截断正文长度并补齐 JSON 输出。 6. 请求失败时重试最多 2 次间隔 1.5 秒。 ## 输出 始终输出 JSON 对象格式如下 {status: success, result: {title: ..., content: ..., links: []}} 失败时 status 为 error并在 error_message 中说明具体原因。 ## 注意事项 - 如果用户提供的是 PDF、图片或其他非网页文件链接请勿调用本技能。 - 目标地址必须完整含协议头否则返回参数错误信息。 - 抓取内容仅限公开页面不得用于绕过访问控制。这份描述里包含足够多的约束信息模型能在多种任务中准确判断是否调用并在调用时正确填参。写完了建议自己用模型多测几次看看触发率和参数准确率再迭代修饰用词。4.3 核心脚本实现三个关键函数逻辑走向清晰main.py的核心部分我拆成三个函数校验、抓取、解析。这样可以避免所有逻辑堆在一个函数里后面测试也好写。import re import requests from bs4 import BeautifulSoup from urllib.parse import urlparse, urljoin from typing import Dict, List, Optional DEFAULT_UA Mozilla/5.0 (compatible; SkillBot/1.0) TIMEOUT 15 MAX_RETRIES 2 def _validate_url(url: str) - tuple: 校验并规范化 URL。返回 (is_valid, cleaned_url, error_msg) if not url: return False, , url is required if not re.match(r^https?://, url): url https:// url parsed urlparse(url) if not parsed.hostname or . not in parsed.hostname: return False, url, finvalid domain: {parsed.hostname} return True, url, def _fetch_content(url: str) - tuple: 发起请求并抓取 HTML。返回 (html_text, error_msg) headers {User-Agent: DEFAULT_UA} last_error None for attempt in range(MAX_RETRIES 1): try: resp requests.get(url, headersheaders, timeoutTIMEOUT) resp.raise_for_status() return resp.text, except requests.exceptions.Timeout: last_error request timed out except requests.exceptions.HTTPError as e: code e.response.status_code if e.response is not None else unknown last_error fhttp error {code} if code in (401, 403, 404): break # 这些状态重试也没意义 except requests.exceptions.RequestException as e: last_error fnetwork error: {str(e)[:120]} return , last_error def _parse_html(html: str, base_url: str, max_chars: int) - Dict: 解析 HTML提取标题、正文和链接。 soup BeautifulSoup(html, html.parser) for tag in soup([script, style, noscript]): tag.decompose() title h1 soup.find(h1) if h1: title h1.get_text(stripTrue)[:200] else: title_tag soup.find(title) if title_tag: title title_tag.get_text(stripTrue)[:200] content soup.get_text(separator\n, stripTrue) content re.sub(r\n{3,}, \n\n, content) if len(content) max_chars: content content[:max_chars] ... links: List[str] [] for a in soup.find_all(a, hrefTrue): absolute urljoin(base_url, a[href]) if absolute.startswith((http://, https://)) and absolute not in links: links.append(absolute) return {title: title, content: content, links: links}主逻辑没什么花哨的入口函数先校验再抓取最后解析。出错时所有中间过程都会返回可读的错误信息方便模型往下接话。这里有个细节值得留意错误信息要切断不要超出合理长度。第一次写这个技能时网络异常信息我直接str(e)全部输出结果用户看到一坨堆栈模型也不知道怎么处理。现在统一截断到 120 字符一句话说明白原因实际效果好得多。4.4 连接模型接入 Agent 时的触发与返回处理技能写好了怎么接到 Agent 上不管你是用 OpenAI 的 function calling、Anthropic 的 tool use还是自研的 Agent 框架逻辑都差不多在系统提示词或工具列表里声明这个技能让模型知道“有这么个东西可用”。具体接入时我会关注三个点第一工具名对应技能目录描述直接引用SKILL.md中的内容。这本身就是一个动态加载策略建议直接把描述文本塞进 API 请求不用人工精简。第二模型的返回要强约束。比如我要求模型在输出中明确说明“已调用 fetch_and_read_url 技能参数为 xxx”方便做行为审计。凡是模型自己编造的调用记录一律视为 bug。第三外部环境要配合。技能脚本运行时要能够从进程环境变量或请求上下文中读取超时参数。这样在不同的部署环境里技能可以有不同的表现而不用改代码。5. 测试与调试让技能在任何环境下都稳定可用技能写完之后最忌讳的是什么直接上线。我见过太多人写完一个技能测试两三个正常案例就宣布完工结果生产环境一跑各种边角情况全冒出来了。下面这套测试流程是我长年迭代后固定下来的“出厂标准”。5.1 单元测试把核心函数单独拉出来验证对核心脚本我会保证关键函数都有对应的测试用例。以fetch_and_read_url为例测试覆盖面大概是这样测试用例输入场景预期行为URL 缺协议头example.com/page自动补全为https://example.com/page无效域名httpx://abc返回 error错误信息包含invalid domain超时场景连接一个不可达 IP重试 2 次后返回request timed out403 拒绝服务器返回 403不重试返回http error 403内容截断超长页面正文按照max_chars截断并追加省略号外链抽取页面含 5 个链接返回全部链接且去重均为绝对地址测试代码用 pytest 就可以自己本地跑一遍再把测试文件一并提交到仓库。这里有个额外的建议tests/fixtures/里放几个 HTML 样本文件这样测试的时候不用真的发网络请求既快又稳定还能避免测试时被目标网站反爬限制。5.2 集成测试模拟模型调用技能的真实链路单元测试只能验证脚本本身但技能最终是由模型触发的所以集成测试必不可少。我会写一个模拟脚本人为构造一段模型决策逻辑调用技能入口函数传参方式和真实 Agent 完全一致。这样能同时验证两件事第一模型传参格式能不能被技能正确解析。真实场景里模型填参偶尔会多带几个空格或者把布尔值写成字符串true。我在技能入口处统一加了一轮参数规整保证这类情况也能正确处理。第二技能的返回结果是否足够友好。我会刻意构造错误场景传一个 404 链接、传一个空 URL然后看返回的 JSON 能否支撑模型生成一段合理的解释。如果错误信息过于技术化模型容易跟着跑偏这时候就要改错误信息措辞。5.3 回归测试确保迭代不破坏已有功能技能的迭代频率其实挺高的可能过两周就要改一次提示词或脚本逻辑。改完之后跑了全部测试吗这是很多人的盲区。我的习惯是每次改动至少把该技能的所有测试用例跑一遍再跑一遍和它相关联的上下游模块的用例。如果你有 CI 环境把技能测试挂进流水线这就是性价比极高的自动化投入。关于测试我最后想说的一个点测试用例本身也是技能资产的一部分。一个技能换一个人维护如果它有完整的测试集接手成本会降低很多。之前我带团队时发现测试不完整的技能重构时没人敢动最后全变成没人维护的“僵尸技能”。所以哪怕技能简单也建议至少把核心函数的测试补齐。6. 常见问题与排查技巧实录实操过程中遇到的问题好多是第一次碰的时候怎么都想不通、事后才拍大腿的类型。我把自己踩过以及帮别人排查过的典型问题整理出来做成一个速查表希望能帮你节省一些本可以避免的调试时间。现象根本原因快速排查方法解决方案技能从未触发描述词与任务语境不匹配查看调用日志看模型是否在类似场景下选择了其他工具重写 description加入正面和反面示例参数总是缺失模型从用户话术中提取不到信息模拟对话请求打印完整 tool call 请求体描述中补充“缺少参数时必须追问用户”的指令技能执行慢脚本加载了不必要的重型库python -X importtime your_script.py看加载耗时裁剪依赖延迟导入非核心模块输出被下游解析失败返回结构不稳定字段缺失或类型不统一手动跑一次技能用json.loads验证输出在入口处增加合规断言强制 schema多技能互相抢占触发权技能描述之间有重叠场景列出所有技能的意图声明找交集明确优先级重叠场景统一归一个技能处理目标网站限制请求被反爬虫策略拦截查看响应头和状态码区分 403/429调整 UA、降低频率必要时配置代理走正规代理服务6.1 技能“假装触发成功”怎么办这个问题的本质是模型在回复文本里说“已调用技能”但实际上工具调用的请求里根本没有这段调用记录。出现这种情况通常是技能描述里缺少“必须真实发起工具调用”的强约束。我在系统提示词里会专门加一句“未经实际调用不得声称使用过任何工具。若技能调用失败明确告知用户失败原因。”同时在上层的安全日志里做交叉校验凡是无调用记录却声称调用的输出直接打回重放。6.2 模型传参“语义正确但格式全错”怎么办典型场景用户说“帮我看看那个网页”模型识别到用户意图是抓取网页但不知道该传什么 URL 参数于是传了一个空字符串或“那个网页”这样的文本。这种情况下不要指望模型“变聪明”要在技能内部做防御参数缺失时直接返回需要用户澄清的结构化信息。比如fetch_and_read_url的做法是{status: error, error_message: missing_required_parameter: url, result: null}这条错误信息返回到模型那里模型会意识到自己漏了参数从而主动追问用户补齐链接。你会发现这比在提示词里反复强调“你必须提取 URL”奏效得多因为问题被提前拦截在了技能内部。6.3 多技能编排时如何避免冲突当 Agent 挂载了五六个技能之后冲突会发生得很微妙。比如你既有一个“危险域名检测”技能又有一个“URL 内容抓取”技能用户说“看看这个网址安不安全”两个技能描述里都包含“查看网址”这种词模型就容易犯迷糊。我的处理方式是在 SKILL.md 里不只写“做什么”也明确写“不做什么”。例如危险域名检测的描述末尾加上“仅用于域名安全评估不做内容解析若用户需要查看页面内容应选择其他技能。”写完描述之后我会人为构造几个边界测试用例去跑确保哪些技能该触发、哪些不该逻辑清晰。7. 写在最后的经验体会这套技能体系我从最初几个简单脚本折腾到现在最大的感受是技能的边界感和工程质量决定了一个 Agent 项目的天花板。模型的能力固然重要但它只是执行层的一环真正沉淀价值的恰恰是这些看似琐碎、容易被忽视的技能设计与封装。我个人在实际操作中最受益的一个习惯是每个技能上线前都强制自己写一份“一行价值说明”。写不出来就说明技能定位还不够清晰继续打磨。另一个受用的小技巧是技能里的错误日志不记录给用户看而是单独保存一份给开发者看的明细版本问题定位快很多。这些细节单个看不值钱叠在一起就是靠谱和凑合之间的区别。如果你正打算给项目引入技能机制这里建议直接从一个小场景开始先把一个技能的完整链路跑通再逐步扩展到更多场景。技能系统的复杂度会随着数量增长先积累最小可用版本后面再持续丰富、迭代。这个方向后续可做的事还有很多技能的版本管理、技能之间的组合编排、技能的自动发现与推荐每一块都值得单独深挖。希望这篇文章能给你一个足够扎实的起点。
+Skills云上及Windows本地部署小白也能学会：TaoToken统一Key接入实操)
