写 Agent Skill 这事儿我从去年开始反复折腾。先说结论好用的 Skill 不是“一段能跑的脚本”而是一套把边界、输入输出、错误处理、提示词节奏都提前定义好的小系统。Model 再聪明也扛不住糊里糊涂的调用方式真正拉开差距的是你在 Skill 里塞了多少设计。这篇文章想聊的就是“怎么写一个好用的 Agent Skill”。它的核心在于回答三件事这个 Skill 应该解决什么问题Agent 怎么知道你什么时候该用、怎么用出错了怎么办把这三个问题想透后面所有代码和配置文件才有意义。如果你正在做 Agent 开发或者已经在用 Codex、Claude、OpenCode 这类工具想把重复性的操作沉淀成可复用的能力这篇内容会帮你少走很多弯路。下文会从设计思路、骨架搭建、完整实操到问题排障把验证过的方法和踩过的坑一次说清楚。1. 先弄明白Agent Skill 到底是什么1.1 从一个“能干活”和“只会聊天”的区别说起很多人最开始理解的 Agent就是一个能对话的机器人。但真正干活的时候你会发现问题远不止“模型强不强”这么简单。就拿“帮我读一篇论文并整理成笔记”这个需求来说。你直接丢给一个裸模型它大概率会一本正经地编造摘要甚至会生成一个看起来很像那么回事、但从未真正打开过的链接。你换一个大参数模型情况可能会好一点但依然不稳定——因为模型并不知道你的工作流是先下载 PDF、提取正文再按模板整理还是直接调用某个外部检索服务。Agent Skill 就是用来补上这一环的。它是一段“带说明书的工程代码”把某项任务的处理流程、输入格式、输出规范、异常分支都固定下来。Agent 在运行时读取这份说明书配合执行脚本就能从“泛泛而谈”变成“稳定交付”。换句话说Skill 是 Agent 手边的一本岗位手册你不是让模型自由发挥而是给它一套“遇到什么情况就翻哪一章”的操作规程。这样出来的结果稳定性会远远高于裸 prompt。1.2 Skill 和 Agent、Harness、插件的边界聊 Skill 之前有两个概念很容易混Harness 和 Agent。Harness 是“外壳”负责管理模型、工具、权限、循环和退出条件相当于整个运行框架。Agent 是“决策者”根据用户目标决定下一步调用哪个工具、读哪份资料、写哪段代码。Skill 则更像“技能包”是 Agent 可随时加载的专业能力模块。再打个比方Harness 是厨房动线Agent 是厨师Skill 是菜谱。动线决定了厨房怎么走不绕路厨师决定今天做哪道菜而菜谱告诉他每一步该放什么料、火候多久。没有菜谱的厨师全凭发挥有了菜谱就能稳定复制口味。至于插件Plugin和 Skill 的边界更微妙。多数框架里插件偏“基础设施”比如文件读写、网络请求、数据库操作这些通用能力Skill 偏“业务专业能力”比如“写一篇周报”“分析这份 Excel 里的销售趋势”“把这篇论文转成思维导图大纲”。实践中并不需要硬掰但如果你想写的 Skill 能被复用、被分发就要尽量保持在“业务任务”这个粒度而不是越做越像通用工具函数。1.3 好 Skill 的三条判断标准我自己判断一个 Skill 好不好用主要看三条够简单也够狠第一条Agent 知道什么时候该用。如果描述写得不清不楚模型很容易在不需要的时候强行调用或者需要的时候想不起来。这跟工具说明的命中率直接相关。第二条输入输出稳定。同样一个 URL、一份文档、一个参数这次能跑下次也能跑模型版本换了Skill 依然不出幺蛾子。凡是靠“运气”成功的调用都算不上好 Skill。第三条错误可以追溯。出问题时要么能明确报错“是网络问题、格式问题还是权限问题”要么能自动降级处理。最怕的就是静默失败——输出一个看起来正常、实际错误的结果这种坑最难排查。2. 写 Skill 之前先把骨架设计对2.1 任务拆解从“我要什么”到“我要定义什么”很多初次写 Skill 的人上来就写代码结果写出来的东西只能在某一个非常具体的场景里跑一次换个输入就废。其实正确的顺序是先把任务拆干净。我习惯把目标拆成四个层级意图层、信息层、处理层、表达层。意图层回答“用户到底想干成什么”。比如“总结这篇论文”意图可能是“快速了解核心贡献”也可能是“准备一篇答辩演讲稿”两者需要的信息完全不一样。信息层回答“需要哪些输入、从哪获取”。是一个 URL、一个本地文件路径还是需要 Agent 先去检索多份资料这些输入来源决定了脚本的入口设计。处理层回答“中间要做哪些关键动作”。比如抓取网页、提取正文、清洗广告噪音、按章节切分、生成摘要。这部分的逻辑要可测试、可分解。表达层回答“最终输出成什么样”。是纯文本要点是 Markdown 结构化报告还是 Json 供下游程序继续消费输出协议一旦确定Agent 后续就能接着用。把四个层级都写清楚Skill 的骨架自然就出来了。很多翻车案例问题恰恰出在“分析不足”意图没弄清楚就去写脚本输出格式没定Agent 拿到结果以后又得自己猜着加工必然不稳定。2.2 输入输出协议是命根子如果说 Skill 有一个命脉那就是输入输出协议。模型不像传统程序它不会老老实实按“参数表”一个一个传参。它更习惯看的是一段“自然语言的任务描述”然后根据 Skill 文档里的指令把参数自己填进命令里。所以你的输入协议要同时写给“模型”和“脚本”两头看。给模型看的是这段描述“当用户给出一个 URL 并希望获取文章正文时使用python web_summary.py url。URL 必须是 http:// 或 https:// 开头。如果链接看起来是本地文件路径不要调用此 Skill。”给脚本看的是命令行的参数约定、环境变量、退出码。脚本要足够宽容能处理带空格的 URL能识别奇怪的编码必要时能从 stdin 读取内容防止参数过长导致报错。输出协议同样重要。我强烈建议固定输出为“结构清晰、易被后续处理”的格式。要么是 Markdown要么是 JSON。纯自然语言输出虽然阅读体验好但 Agent 想拿结果再加工就得二次解析容易出错。我自己常用的输出模板大概是这样的先输出一行状态标记比如STATUS: OK或STATUS: ERROR接下来再输出正文或错误信息。这样 Agent 判断成败只需要看第一行不需要猜。2.3 单一职责小、清楚、可组合Skill 最容易犯的一个毛病就是越写越大最后变成一个“全家桶”。今天加一个抓取明天加一个翻译后天再加一个正则清洗最后几百行代码谁都不敢动。我的原则是一个 Skill 只解决一个任务。比如“论文工具”这种规划看起来很合理但你最好拆成paper-fetch下载论文、paper-summarize生成摘要、paper-mindmap生成大纲 / 思维导图。每个小 Skill 独立测试、独立进化Agent 根据用户具体的问题做编排。这是拆开的好处可组合性。真正复杂的任务往往不是一个 Skill 从头干到尾而是 Agent 依次调用多个小 Skill把前一个的输出喂给后一个。这比一个巨大 Skill 把所有逻辑写死要可靠得多也方便后期维护和分享给其他人复用。当然拆粒度也要适度。如果拆得太碎一个简单任务要串五个 Skill模型编排开销反而变大。我的经验是一个 Skill 的操作步骤尽量控制在三到五步能用一个脚本解决的就不要拆成两个。3. 实操示范从头写一个真正能用的 Skill3.1 生态背景Claude Skills 的 SKILL.md 形态现在主流 Agent Skill 的形态很大程度上受 Anthropic 的 Claude Skills 影响一个目录里放一个SKILL.md说明文件再加若干脚本和资源文件。OpenCode、Codex 这类 Coding Agent 也陆续支持类似结构已经成为一种事实标准。这种“Markdown 说明书 脚本”的形态有个很大的好处说明文件是纯文本模型读起来容易脚本是真正的可执行逻辑跑起来可靠。两者各司其职互不污染。所以下面实操我会围绕这个形态展开。如果你用的是自己的 Agent 框架也可以把同样的逻辑套进去——核心不是文件格式而是“说明 实现”的分离思想。3.2 Skill 的标准目录与元数据文件先创建一个标准目录结构web-summary/ ├── SKILL.md ├── web_summary.py ├── requirements.txt └── assets/ └── prompt_template.mdSKILL.md是 Skill 的入口Agent 会先读它。文件开头用 YAML frontmatter 写明元信息方便框架做索引。下面是一个例子--- name: web-summary description: 抓取网页正文并生成摘要或要点列表。当用户给出 URL 且希望了解文章内容、提炼观点、整理笔记时使用。不要用于本地文件。 ---YAML frontmatter 里的description特别关键。它决定 Agent 什么时候选择这个 Skill。写描述时要用第三人称、基于触发场景而不是“这个工具能做什么”的空话。比如别写“一个网页抓取工具”而要写“当用户想要总结某个网页链接的内容或需要从网页中提取正文文本时使用”。requirements.txt用来声明依赖。这部分看起来不起眼但如果你打算把 Skill 分享给别人它就是“能不能直接跑起来”的门面。requests2.31.0 beautifulsoup44.12.23.3 核心脚本一个网页摘要 Skill 的完整实现接下来是核心的web_summary.py。在这个例子里我主要是做一个网页正文提取器输入 URL输出页面标题和正文纯文本供上层 Agent 再生成摘要。脚本逻辑控制在 50 行左右方便维护。#!/usr/bin/env python3 web_summary.py - fetch and extract readable text from a web page. import sys import requests from bs4 import BeautifulSoup HEADERS {User-Agent: Mozilla/5.0 (compatible; AgentSkill/1.0)} MAX_CHARS 5000 def extract_title(soup): if soup.title and soup.title.string: return soup.title.string.strip() h1 soup.find(h1) return h1.get_text().strip() if h1 else def extract_main_content(soup): for tag in soup([script, style, nav, footer, aside]): tag.decompose() text .join(soup.get_text().split()) return text[:MAX_CHARS] def main(): url sys.argv[1] if len(sys.argv) 1 else if not url: print(STATUS: MISSING_URL) print(请提供以 http:// 或 https:// 开头的网页 URL。) return 1 try: resp requests.get(url, headersHEADERS, timeout10) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) print(STATUS: OK) print(TITLE:, extract_title(soup)) print(---CONTENT---) print(extract_main_content(soup)) return 0 except requests.Timeout: print(STATUS: ERROR) print(ERRORTYPE: TIMEOUT) print(请求超时请检查 URL 或稍后重试。) return 1 except requests.RequestException as e: print(STATUS: ERROR) print(ERRORTYPE: REQUEST) print(f请求失败: {e}) return 1 if __name__ __main__: sys.exit(main())这个脚本有一个关键点状态行。它把结果分成STATUS: OK、STATUS: ERROR、STATUS: MISSING_URL三种状态每一种的核心信息都放在第二行最后才是详细文本。Agent 判断下一步动作时只需要先扫状态行不需要把全文读完再猜。MAX_CHARS 5000是为了防止网页正文太长导致上下文爆炸。你可能会担心截断会丢信息没错但这不是脚本该解决的问题。更合理的做法是在SKILL.md里告诉 Agent如果正文长度接近上限先分段处理或者优先阅读开头部分以理解整体结构。3.4 SKILL.md 的正文结构模型调用时要能“照着做”YAML frontmatter只是入口真正让模型知道怎么工作的是SKILL.md的正文部分。我习惯把正文按“何时使用、准备工作、执行步骤、输出解析、注意事项”五段来写。# Web Summary ## 何时使用 - 用户给出网页链接希望了解内容大意、提取要点、生成摘要。 - 用户提到“读一下这篇文章”“总结这个网页”“帮我看看这个链接”等意图时。 - 目标必须是以 http:// 或 https:// 开头的网页不是本地文件。 ## 准备工作 1. 确认目录下已安装依赖 bash pip install -r requirements.txt如果脚本缺少依赖先安装再运行。执行步骤运行python web_summary.py url。读取输出结果。输出解析第一行STATUS: OK表示成功随后可看到页面标题和正文。STATUS: ERROR表示请求失败读取ERRORTYPE字段区分是超时还是其他请求错误。STATUS: MISSING_URL表示没有传入 URL需要重新补齐参数。注意事项不要修改脚本内容来适配某个网页除非你确认是通用 bug。如果正文接近 5000 字截断请提示用户“正文较长已截断”并主动提供分段总结建议。不要用该 Skill 处理 PDF、本地文件或需要登录的页面。这个文档的核心判断逻辑很简单**让模型读了就知道“什么情况用遇到输出怎么看出错怎么反馈”**。你会发现这里并没有堆砌太多技术术语而是把 Agent 需要做的决策点都摆了出来。 ### 3.5 让 Agent 真正“读到”你的 Skill加载与测试 写完文件不等于 Skill 已经生效。如果你用的是 Claude 这类商用 Agent 的 Skill 加载机制通常是把目录放到指定的 skills 文件夹如果你用的是自己搭的框架那要考虑把 Skill 目录列表注入系统提示词或者让 Agent 能通过工具扫描可用 Skill。 测试时我没有只测“正常情况”而是把这个 Skill 放进一套固定的验证清单里 - 一个正常的博客 URL - 一个会超时的 URL - 一个不存在域名的 URL - 一个无法直接访问、返回 403 的 URL - 一个没有 title 和 h1 的页面。 通过验证清单我才放心这个 Skill 能在真实场景里扛住各种边角情况。 ## 4. 常见陷阱与排查技巧 ### 4.1 环境问题依赖、路径、权限 Skill 跑不起来八成都不是逻辑问题而是环境问题。最常见的是这几个 **Python 环境不一致。** 本地机器装了 requests但运行 Agent 的进程用的是另一个虚拟环境什么都没装。我的做法是在 SKILL.md 的准备步骤里明确列出 pip install -r requirements.txt并且在脚本顶部做一次非常轻量的依赖检测缺失依赖时给出明确提示而不是抛一个让模型都迷惑的 Stack Trace。 **工作目录不对。** 很多框架调用 Skill 时并不会自动 cd 到 Skill 目录。如果脚本里用了相对路径读取资产文件就会因为当前工作目录不对而报错。规避方式很简单脚本里所有路径都用 Path(__file__).parent 拼出来不要用裸相对路径。 **权限问题。** 如果你的 Skill 需要写文件、读特定目录或者调用系统命令一定要先确认进程权限足够。这个问题在桌面端 Agent 尤其常见弹个权限窗口还好最怕的是静默拒绝——你以为写进去了实际什么都没发生。 ### 4.2 上下文失控Skill 自己把 token 烧完了 真正开始跑复杂任务时你会发现 Skill 输出的东西经常把上下文窗口挤爆。比如把一篇全文 2 万字的长文直接塞进输出模型还没开始总结上下文就已经快满了。 解法是两个方向**入口限制**和**输出压缩**。入口限制是在脚本里就抓好关键内容比如只提取前 3000 字或指定段落输出压缩是脚本先做一次轻量预处理比如去重空行、合并冗余段落、去除页脚页眉再把精简后的内容交给模型。 我在 web_summary.py 里加的 MAX_CHARS 5000 就是入口限制。但要注意如果网页是学术论文或者长文分析直接截断可能损失重要信息。更聪明的做法是在 SKILL.md 里告诉 Agent当发现正文接近截断限制时优先总结开头、提取各级标题和关键段落然后向用户说明“内容较长建议分段阅读”。 ### 4.3 调用不稳定Agent 为什么常常“看不见” Skill 这是被问得最多的一类问题Skill 文件明明写好了Agent 却总是不调用或者随机漏调。 第一个排查点**description 写得太宽泛**。模型选择 Skill 的时候本质上是在做语义匹配。如果 description 写的是“这是一个网页抓取工具”当用户说“帮我把这篇新闻总结一下”时模型未必能联想到要调用它。但如果你写的是“当用户提到阅读、总结、提取某个网页链接的内容时使用”命中率会高很多。 第二个排查点**Skill 太多模型选择不过来**。当系统里挂了十几个描述相近的 Skill模型很容易挑花眼。我的建议是保持每个 Skill 的边界足够清楚必要时在描述里写上“不要用于……”减少误匹配。 第三个排查点**框架没有把 Skill 注入到模型的可见信息里**。这个很隐蔽。有的框架把 Skill 列表放在一个“隐藏系统消息”里模型看不到或者列表太长被截断了。出现这种问题时你可以先在调试模式里打印出模型接收到的完整系统提示确认 Skill 文件是否真的被加载。 ### 4.4 常见问题速查表 我整理了一份速查表基本上把维护 Skill 时最常见的问题都概括了。你可以直接照着排查。 | 现象 | 可能原因 | 处理方式 | |---|---|---| | Skill 完全不触发 | description 太泛 / 未加载 | 重写触发场景描述检查加载路径 | | 触发但不跑脚本 | 模型没看懂执行步骤 | 把执行命令写成单行、可复制格式 | | 脚本报错 ModuleNotFound | 依赖未安装 / 环境不对 | 检查虚拟环境和 requirements.txt | | 输出超长上下文暴涨 | 缺少截断或压缩逻辑 | 在脚本入口加长度限制 | | 结果生成“看起来对但错” | 异常分支被静默吞掉 | 增加状态行ERROR 时明确返回错误 | | 用相对路径读文件失败 | 工作目录不是 Skill 目录 | 用 Path(__file__).parent 定位资源 | | 同一输入两次结果不同 | 外部依赖不稳定 / 网络问题 | 增加超时、重试与固定 User-Agent | ### 4.5 调试 Skill 时最实用的一套手法 如果你问我调试 Skill 有什么私藏技巧我会说**不要直接在真实任务里反复试而是先把它当成一个普通命令行程序去单测**。 也就是说你先把python web_summary.py url跑通确认返回的各种状态都符合预期再把它挂到 Agent 环境里。很多开发者跳过这步直接在 Agent 里调用一旦出错根本分不清是脚本的 bug、模型的调用问题还是输出解析的问题。 另外我给每个 Skill 都预留了一个“自检模式”。比如在脚本里加一个 --self-check 参数传入测试 URL输出预期结果和一个状态行。这样无论是手动验证还是 CI都能快速确认 Skill 没有因为环境变化而退化。别小看这个动作项目一旦多起来它可以救你很多次。 ## 5. 让 Skill 从“能用”变成“好用”的经验之谈 ### 5.1 命名和描述是隐形的另一半 前面提过描述的重要性这里我想再展开一点。很多人花了大量时间打磨代码却只给 description 写一行干巴巴的话结果模型根本识别不了。这就像一个函数文档只写了函数名没写参数和返回值别人根本不知道怎么调用。 我的习惯是给 description 写两到三句话包含三部分**触发条件、任务内容、排除情况**。比如 当用户提供一个网页 URL并要求总结、提取要点或快速了解内容时使用。也适用于将网页内容转为笔记、翻译或生成大纲。不要用于本地文件、PDF 或需要登录的后台页面。 这一小段描述比一整个复杂脚本更能决定 Skill 的实际体验。Skill 代码写得再漂亮模型找不到入口一切都白费。 ### 5.2 错误处理一门被忽视的必修课 新手写 Skill最容易忽略的就是异常分支。因为“正常路径”好写异常分支很麻烦而且看起来不产生价值。但真实场景里异常才是常态。 比如请求网页你以为是稳定返回 HTML结果它可能重定向、可能 403、可能返回一个反爬挑战页、可能正文是图片载入。没有异常处理的 Skill会把所有这些情况都当成“成功”然后把垃圾内容当作正文传给模型——这是一种隐蔽又危险的失败。 我的做法是把错误明确分成几类 - 输入类错误URL 缺失、格式错误 - 外部资源错误网络超时、DNS 失败、HTTP 状态异常 - 解析类错误页面结构不符合预期无法提取正文 - 运行类错误脚本本身异常 每一类错误都在输出里带上一个明确代号比如 ERRORTYPE: TIMEOUT 或 ERRORTYPE: PARSE。这样 Agent 拿到错误后才能给出对应的用户提示而不是复述一段代码报错。 ### 5.3 版本管理与跨框架迁移 最后聊一个容易被忽略的问题Skill 也值得用版本管理。 我见过不少项目Skill 文件直接堆在某个文件夹里改着改着连自己都忘了哪份是最新的。更麻烦的是同一个 Skill 可能在多个 Agent 框架里使用每个框架对元数据、文件结构的要求还不完全一样。 我的实践是把每个 Skill 当成一个小仓库来管理。目录内保持固定的结构README 写清楚适用场景和变更记录。如果需要在不同框架之间迁移就把 SKILL.md 视为“标准接口层”脚本实现尽量保持框架无关——用标准库或最少依赖避免绑死某个运行时。 还有一个容易被忽略的点**Skill 的更新会影响历史任务的复现**。如果你在某次 Agent 评测里用了一套参数后来改了脚本再想复现结果就可能对不上。所以测试和评估的时候最好把 Skill 的版本号一并记录下来。这一点对长期做 Agent 评测和项目迭代的人来说特别重要。 ### 5.4 从“自己用”到“分享给别人” 如果你想把 Skill 发布出来供别人使用还有几个额外要求。 首先文档必须无歧义。你自己用的时候可能知道某个命令要在哪个目录执行但别人不知道。所以 SKILL.md 里要把“前置条件、依赖安装、运行样例、常见报错”都写全。其次不要假设别人的机器上有某些库、有某些外部服务尽量让脚本在最少依赖下也能跑。再就是命名要统一建议采用 作用域-功能 的形式比如 web-summary、paper-fetch、book-to-skill天然避免重名。 我见过很多优秀的 Skill代码逻辑本身并不复杂但它们的文档写得极其细致连“输入 URL 超时后应该怎么提示用户”都提前定义好了。这正是好 Skill 和普通脚本之间的分水岭。 ## 最后说点实在话 写了这么多我最大的体会是写 Agent Skill 从来不是“写代码”这么简单它更像是在设计一个小小的“人机协作接口”。你既要把事情讲清楚又要把边界划明白还要给模型留出足够的灵活度。这个平衡点不亲手踩几次坑是拿捏不准的。 回到最开头那句话好用的 Skill 是一套小系统。它的核心是稳定的输入输出、明确的错误处理、和一份能让模型“照着做”的说明文档。想入门的开发者不妨先从一个最简单的网页摘要 Skill 开始练手把它跑通、调稳、写好文档然后再去挑战更复杂的论文分析、数据清洗或者工作流编排类 Skill。 还有一个小心得当你发现某个 Skill 经常被模型绕开不调用时不要急着改代码先把它在真实对话里的“被调用率”记录下来。有时候你只是调整了一下 description 里的措辞从“工具说明”改成“任务触发场景”效果就会有明显变化。这个小细节是我在实际项目中试过无数次后才总结出来的分享给你。