1. 从“skills”这个热词说起：它到底在解决什么问题
最近半年，不管是在技术社区、开发者群聊还是各类工具讨论区，“skills”这个词出现的频率高得离谱。很多人第一次看到“Agent Skills”或者“Claude Agent Skills”的时候，第一反应是“这不就是个插件系统换了个名字吗”，但真正上手用过之后会发现，它想解决的根本不是插件的问题，而是能力复用与组合的问题。
我最早接触这个概念是在一个自动化内容处理的场景里。当时团队需要让一个智能体完成“抓取指定主题的公开资料、整理成结构化笔记、再生成一份可读性强的摘要”这样一条链路。如果按传统做法，要么写一个庞大的提示词把所有逻辑塞进去，要么拆成多个独立脚本用代码串起来。前者维护起来是灾难，后者则失去了智能体本身灵活推理的优势。而 skills 这套机制恰好卡在中间：它把一项具体能力封装成一个可描述、可调用、可组合的单元，让智能体在需要的时候自己去“取用”，而不是把所有东西都硬编码在一开始。
这就是为什么“skills”会在短时间内衍生出这么多相关搜索词——agent skills测试、codex skills、skills开发、skills推荐、skills大全。大家关心的不是概念本身，而是这东西怎么用、去哪找、怎么自己写、写完怎么测。我写这篇东西的目的，就是把这几个月踩过的坑、试过的方案、以及一些不太容易在官方文档里看到的细节，完整地摊开讲一遍。不管你是刚听说这个词想搞清楚它是什么，还是已经在写自己的 skill 但卡在某个环节，下面这些内容应该都能对上你的需求。
2. 核心思路拆解：为什么是“技能”而不是“插件”或“函数”
2.1 从插件到技能：抽象层级的变化
传统插件系统的逻辑是：宿主程序预留一组扩展点，插件在扩展点里注册自己的实现。比如编辑器插件、浏览器扩展，都是这个模式。它的前提是宿主知道自己在哪些地方需要扩展，扩展点是预先设计好的。
但智能体场景不一样。智能体面对的任务是开放式的，你没法提前枚举出“它可能需要哪些能力”。今天让它处理一份表格，明天让它分析一段代码，后天让它根据几张图写一段分镜描述。如果还用插件思维，就得为每一种可能的能力都预留一个扩展点，这显然不现实。
skills 的思路是把抽象层级往上提了一层：它不关心宿主在哪里调用，而是描述一项能力本身是什么、需要什么输入、会产生什么输出、在什么情况下应该被使用。智能体在推理过程中，根据当前任务的需要，自己去判断“我现在是不是该调用某个 skill”。这个判断过程可以是基于描述的语义匹配，也可以是基于显式的触发条件。
打个比方：插件像是给一台机器预留好的标准接口，你只能往那些接口上插东西；而 skills 像是给一个助手一本能力手册，手册里写着“我会做A、B、C，每种能力需要什么材料、产出什么结果”，助手自己翻手册决定用哪一项。
2.2 技能封装带来的三个实际好处
第一个好处是提示词的可维护性。在没有 skills 之前，一个复杂任务的提示词往往会长到离谱，几千字甚至上万字，里面混杂着角色设定、任务描述、输出格式、边界条件、示例。一旦要改其中某个环节，很容易牵一发而动全身。把能力拆成独立的 skill 之后，每个 skill 只关心自己那一小块逻辑，主提示词只需要负责调度和编排。
第二个好处是能力的可测试性。这一点在agent skills测试这个搜索词里体现得很明显。一个独立的 skill 可以单独喂输入、单独看输出，不用把整个链路跑一遍才能验证某个环节对不对。我自己的做法是给每个 skill 准备一组最小测试用例，改完 skill 描述之后先跑这组用例，通过了再放进主流程。
第三个好处是跨项目的复用。你为一个项目写的“提取网页正文”skill，换个项目只要场景类似就能直接拿来用，最多改一下输入输出的字段名。这也是为什么会有skills推荐、skills大全这类需求——大家希望有一个地方能直接找到别人写好的、经过验证的 skill，而不是每次都从零开始。
2.3 一个容易踩的认知坑：skill 不是越细越好
刚开始写 skill 的时候，很容易陷入“把每个动作都拆成一个 skill”的误区。比如“读取文件”一个 skill、“解析JSON”一个 skill、“格式化输出”一个 skill。拆到最后发现，主流程里全是调度逻辑，反而比原来更复杂了。
我的经验是：一个 skill 应该对应一个语义完整的任务单元，而不是一个原子操作。判断标准很简单——如果你能用一句话向一个新人描述这个 skill 是干什么的，而且这句话里不需要出现“然后”“接着”这类连接词，那它就是一个合适的粒度。比如“根据给定主题生成一份结构化摘要”是一个合适的 skill，“读取文件然后解析然后输出”就不是，它应该被合并成一个“处理文件并输出结构化结果”的 skill。
3. 核心细节解析：一个 skill 到底由哪些部分组成
3.1 描述信息：决定 skill 会不会被正确调用
skill 的描述信息是整个机制里最容易被低估的部分。很多人写 skill 的时候把大部分精力花在实现逻辑上，描述随便写两句，结果发现智能体要么不调用这个 skill，要么在不该调用的时候调用。
描述信息通常需要回答三个问题：这个 skill 做什么、什么时候该用它、它需要什么。第一个问题决定语义匹配的准确性，第二个问题决定触发时机的判断，第三个问题决定调用前的参数准备。
我试过的一个反面案例：早期写了一个“文本摘要”skill，描述只写了“对文本进行摘要”。结果在一个需要“提取关键信息”的任务里，智能体没有调用它，而是自己硬着头皮生成了一段质量很差的总结。后来把描述改成“当需要对一段较长的文本进行压缩、提取核心要点、生成简短概括时使用，输入为原始文本，输出为不超过指定字数的摘要”，调用准确率明显上去了。
注意：描述里不要写实现细节，比如“使用某某算法”“调用某某接口”。智能体关心的是能力和适用场景，不是你怎么实现的。
3.2 输入输出定义：契约清晰才能组合
skill 之间要能组合，前提是输入输出的格式是明确的。这里说的明确，不是指“大概知道是什么类型”，而是指字段名、类型、是否必填、默认值、取值范围都要写清楚。
我一般会用类似下面这样的结构来定义：
name: extract_article description: 从一段网页正文中提取标题、作者、发布时间和正文内容 input: raw_html: type: string required: true description: 网页的原始HTML字符串 base_url: type: string required: false description: 用于补全相对链接的基础URL output: title: type: string author: type: string publish_time: type: string format: ISO8601 content: type: string这样定义的好处是，当另一个 skill 需要“文章内容”作为输入时，它可以明确地知道应该从extract_article的输出里取content字段，而不是猜。
3.3 触发条件：显式规则与语义匹配的取舍
触发条件有两种写法：一种是显式的规则，比如“当输入中包含URL且用户要求提取内容时触发”；另一种是纯语义描述，让智能体自己判断。
显式规则的好处是可控性强，坏处是写多了会变得很僵硬，而且很难穷举所有情况。纯语义描述灵活，但对描述的质量要求很高，写不好就容易误触发或者漏触发。
我目前的习惯是以语义描述为主，在容易混淆的场景下补充显式排除条件。比如一个“生成代码”的 skill，我会在描述里写“适用于根据自然语言描述生成代码片段的场景”，同时补一句“不适用于代码解释、代码审查、bug修复等场景”。后面这句排除条件能挡掉不少误调用。
3.4 版本与依赖管理：多人协作时绕不开的问题
当 skill 数量多起来、参与的人多起来之后，版本管理就成了必须面对的问题。我遇到过的情况是：A 改了一个 skill 的输出字段名，B 的流程里还在用旧字段名，结果整个链路静默失败，排查了半天才发现是字段对不上。
比较稳妥的做法是给每个 skill 加版本号，并且在依赖关系里明确指定版本。如果某个 skill 的输出格式发生了不兼容的变化，就升大版本号，依赖方需要显式更新。同时，在 skill 的描述里保留一份变更记录，方便排查问题时回溯。
4. 实操过程：从零写一个可用的 skill
4.1 环境准备与基础结构搭建
不管你用的是哪套支持 skills 的框架，基础结构都大同小异。一般需要一个存放 skill 定义的目录，每个 skill 一个子目录或者一个文件，里面包含描述信息、输入输出定义、以及具体的执行逻辑。
以我最近在用的一个结构为例：
skills/ extract_article/ skill.yaml # 描述、输入输出、触发条件 handler.py # 具体执行逻辑 tests/ cases.json # 测试用例 summarize_text/ skill.yaml handler.py tests/ cases.jsonskill.yaml负责声明，handler.py负责实现，tests/负责验证。这个结构的好处是职责清晰，改描述不会碰到实现，改实现不会影响描述。
4.2 编写第一个 skill：以“提取文章正文”为例
先写skill.yaml：
name: extract_article version: 1.0.0 description: > 从网页原始HTML中提取文章的主体内容，包括标题、作者、发布时间和正文。 适用于需要对网页内容进行后续处理的场景，如摘要生成、内容归档、信息抽取。 不适用于需要完整页面结构分析的场景。 input: raw_html: type: string required: true base_url: type: string required: false output: title: type: string author: type: string publish_time: type: string content: type: string再写handler.py：
from bs4 import BeautifulSoup import re def handle(raw_html, base_url=None): soup = BeautifulSoup(raw_html, "html.parser") title = "" if soup.title: title = soup.title.get_text(strip=True) author = "" author_meta = soup.find("meta", attrs={"name": "author"}) if author_meta: author = author_meta.get("content", "") publish_time = "" time_meta = soup.find("meta", attrs={"property": "article:published_time"}) if time_meta: publish_time = time_meta.get("content", "") for tag in soup(["script", "style", "nav", "footer", "header"]): tag.decompose() content = soup.get_text(separator="\n", strip=True) content = re.sub(r"\n{3,}", "\n\n", content) return { "title": title, "author": author, "publish_time": publish_time, "content": content }这个实现很朴素，但足够说明问题。实际用的时候可以根据目标站点的特点做针对性优化，比如针对某些常见的文章容器选择器做优先匹配。
4.3 测试用例的编写与执行
tests/cases.json里放最小验证集：
[ { "name": "基础文章提取", "input": { "raw_html": "<html><head><title>测试文章</title></head><body><article><p>这是正文第一段。</p><p>这是正文第二段。</p></article></body></html>" }, "expect": { "title": "测试文章", "content_contains": ["这是正文第一段", "这是正文第二段"] } }, { "name": "无标题场景", "input": { "raw_html": "<html><body><p>只有正文没有标题。</p></body></html>" }, "expect": { "title": "", "content_contains": ["只有正文没有标题"] } } ]跑测试的时候，我一般会写一个简单的 runner，把每个用例的输入喂给 handler，然后检查输出是否满足 expect 里的条件。content_contains这种模糊匹配比精确匹配更实用，因为正文提取的结果往往会有细微的空白字符差异。
4.4 把 skill 接入主流程
skill 写好、测好之后，接入主流程的方式取决于你用的框架。有的框架是自动扫描 skills 目录并注册，有的需要显式声明。不管哪种方式，核心都是让智能体在推理时能看到所有可用 skill 的描述，然后自己决定调用哪个。
我自己的做法是在主提示词里加一段说明，告诉智能体“你可以使用以下技能来完成当前任务”，然后把 skill 列表附上。如果框架支持自动注入，那就更省事。
提示：接入之后一定要跑几个端到端的场景，观察智能体是否在正确的时机调用了正确的 skill。这一步能发现很多单独测试 skill 时发现不了的问题，比如描述之间的语义冲突、输入输出字段不匹配等。
5. 常见问题与排查技巧实录
5.1 skill 不被调用：从描述和上下文两头查
这是最常见的问题。排查顺序我一般是这样的：
先看描述是否足够具体。如果描述太泛，比如“处理文本”，智能体很难判断当前任务是否匹配。改成“对长文本进行压缩摘要，输出不超过指定字数的概括”之后，匹配度会明显提升。
再看上下文里是否有更强的信号干扰。比如主提示词里已经明确说了“请直接生成摘要”，那智能体可能就自己做了，不会去调用 skill。这时候要么调整主提示词的措辞，要么在 skill 描述里强调“当需要高质量摘要时优先使用本技能”。
最后看 skill 的注册是否生效。有些框架需要重启或者重新加载才能识别新增的 skill，这个坑我踩过不止一次。
5.2 输出格式不稳定：用 schema 约束而不是靠提示
即使 skill 的 handler 返回了固定格式的字典，经过智能体转述之后，输出也可能变形。比如你返回的是{"title": "...", "content": "..."}，智能体在最终回复里可能写成“标题是xxx，内容是yyy”。
解决办法是在 skill 的输出定义里明确 schema，并且在主提示词里要求“调用 skill 后，严格按照其输出 schema 呈现结果”。如果框架支持结构化输出，尽量开启，能省掉很多格式对齐的麻烦。
5.3 多个 skill 之间的字段对不上
这个问题在 skill 数量多了之后特别常见。A skill 输出content，B skill 期望输入text，中间没有做映射，结果就是空值或者报错。
我的做法是维护一份字段对照表，记录每个 skill 的输入输出字段名和类型。新增 skill 或者修改字段时，先查对照表，看看有没有可以复用的字段名。如果确实需要不同的名字，就在编排层加一个显式的映射步骤，而不是指望智能体自己猜。
| 常见问题 | 排查方向 | 解决手段 |
|---|---|---|
| skill 不被调用 | 描述太泛、上下文干扰、注册未生效 | 细化描述、调整主提示词、重新加载 |
| 输出格式不稳定 | 缺少 schema 约束 | 明确输出 schema、开启结构化输出 |
| 字段对不上 | 命名不统一、缺少映射 | 维护字段对照表、加显式映射 |
| 调用时机错误 | 触发条件模糊 | 补充排除条件、增加正反例 |
| 执行超时 | handler 逻辑太重 | 拆分 skill、加超时和降级 |
5.4 执行超时与降级策略
有些 skill 的 handler 会做比较重的操作，比如请求外部接口、处理大文件。如果不加超时控制，一旦卡住就会拖垮整个流程。
我一般会给每个 skill 设置一个合理的超时时间，超时后返回一个带有错误标记的结果，让主流程决定是重试、跳过还是走降级逻辑。降级逻辑可以是一个更简单的实现，比如“提取正文”超时了就返回原始文本的前若干字符，至少保证流程能继续走下去。
5.5 调试技巧：把 skill 的调用过程打出来
排查 skill 相关问题的时候，最有用的一招是把智能体的调用决策过程打出来。很多框架支持输出推理轨迹，能看到它在每一步考虑了哪些 skill、为什么选了某个、为什么排除了某个。这个信息比单纯看最终输出有用得多。
如果框架不支持，可以在 skill 的 handler 里加日志，记录每次被调用的输入和时间。结合主流程的日志，基本能还原出调用链路。
6. 技能组合与编排：从单个 skill 到完整工作流
6.1 串行组合：前一个的输出是后一个的输入
最简单的组合方式就是串行。比如“提取文章正文”的输出直接喂给“生成摘要”的输入。这种组合的关键是字段对齐，前面提到的字段对照表在这里就派上用场了。
串行组合的另一个注意点是错误传播。如果第一个 skill 失败了，第二个 skill 拿到的就是空输入或者错误数据。所以每个 skill 的输出里最好带一个状态标记，让下游能判断上游是否成功。
6.2 并行组合：多个 skill 同时处理同一份输入
有些场景下，同一份输入需要被多个 skill 分别处理，最后把结果合并。比如一段文本既要提取关键词，又要做情感分析，还要生成摘要。这三个 skill 之间没有依赖关系，可以并行执行。
并行组合的难点在于结果合并。如果三个 skill 的输出格式各不相同，合并逻辑就会很复杂。我的做法是让每个 skill 的输出都遵循一个统一的外层结构，比如都包含status、data、error三个字段，这样合并的时候只需要处理data部分。
6.3 条件组合：根据中间结果决定下一步
更复杂的场景需要根据中间结果动态决定下一步走哪个分支。比如先判断文本的语言，如果是中文走中文处理链路，如果是英文走英文处理链路。
这种组合方式对 skill 的描述要求更高，因为智能体需要理解“在什么条件下应该选择哪个分支”。我一般会在主提示词里把分支逻辑写清楚，而不是指望智能体自己推断。
6.4 编排层的职责边界
编排层不应该包含具体的业务逻辑，它只负责调度和协调。具体的处理逻辑都在 skill 里。这个边界如果模糊了，编排层就会变得越来越臃肿，最后又回到“一个大提示词包打天下”的老路。
我见过的一个反例是：编排层里写了一堆条件判断和数据转换，skill 反而成了简单的工具函数。这样做的后果是，改一个业务规则要动编排层，而编排层往往是最难测试的部分。正确的做法是把业务规则下沉到 skill 里，编排层只做“什么时候调用哪个 skill”的决策。
7. 技能的分发、复用与生态现状
7.1 本地复用：目录结构与命名规范
在单个项目内部复用 skill，最重要的是命名规范。我一般遵循“动词_名词”的格式，比如extract_article、summarize_text、translate_content。这样从名字就能看出 skill 的功能，也方便在编排层引用。
目录结构上，我习惯按功能域分组，比如skills/extraction/、skills/transformation/、skills/generation/。这样 skill 多了之后不至于乱成一团。
7.2 跨项目复用：把 skill 做成独立包
如果多个项目都需要用到同一组 skill，可以考虑把它们抽成一个独立的包，通过包管理工具分发。这样版本管理、依赖声明、更新升级都有成熟的机制可以用，不用自己造轮子。
抽包的时候要注意把 skill 的描述信息和实现逻辑一起打包，因为描述信息是智能体调用决策的依据，缺了它 skill 就没法被正确使用。
7.3 社区生态：去哪找现成的 skill
目前已经有一些社区在收集和分享 skill 定义，覆盖的场景从文本处理到代码生成到数据分析都有。找现成 skill 的时候，我一般会看几个点：描述是否清晰、输入输出是否明确、有没有测试用例、最近有没有更新。这几点都满足的，基本可以直接拿来用或者稍作修改。
不过也要注意，别人的 skill 是针对别人的场景写的，直接拿来用之前最好先在自己的数据上跑一遍测试用例，确认行为符合预期。
7.4 安全与权限：调用外部能力时的边界
如果 skill 的 handler 会访问外部资源或者执行有副作用的操作，就需要考虑权限控制。比如一个“发送通知”的 skill，不应该在任何情况下都能被随意调用，而应该加上显式的确认步骤或者权限校验。
我的做法是把有副作用的 skill 单独标记出来，在编排层里对这类 skill 的调用加上额外的确认逻辑。同时，在 skill 的描述里明确写出它的副作用，让智能体在决策时有所感知。
8. 我踩过的几个坑和对应的解法
第一个坑是描述写得太抽象。早期写了一个“优化文本”的 skill，描述就一句话。结果智能体要么不用它，要么在不该用的时候用。后来把描述改成“对文本进行润色，改善流畅度和可读性，不改变原意，适用于草稿修改场景”，调用准确率才上来。
第二个坑是输入输出没有做校验。有一个 skill 期望输入是 JSON 字符串，但上游传过来的是已经解析好的字典，结果 handler 里解析失败，整个流程中断。后来在 handler 开头加了一个类型检查和兼容处理，既能接受字符串也能接受字典，问题就解决了。
第三个坑是测试用例覆盖不够。有一个 skill 在正常输入下表现很好，但遇到空输入或者超长输入就出问题。后来补了边界用例，才发现空输入时没有做保护，超长输入时没有做截断。这两个问题在端到端场景里很难复现，因为正常流程很少走到这些边界。
第四个坑是版本升级没有做兼容。改了一个 skill 的输出字段名，但没有通知依赖方，结果依赖方的流程静默失败。后来养成了习惯：任何不兼容的改动都升大版本号，并且在变更记录里写清楚影响范围。
第五个坑是过度依赖智能体的自动决策。有些场景下，智能体选择的 skill 并不是最优的，但因为它“看起来也能用”，就没有被拦截。后来在编排层加了一些硬性规则，比如“当输入是URL时，必须优先使用 extract_article”，才把这类问题控制住。
9. 写给准备开始写 skill 的人
如果你刚开始接触 skills，我的建议是从一个小而完整的场景入手，不要一上来就设计一个大而全的技能体系。选一个你日常工作中反复出现的任务，把它封装成一个 skill，跑通从描述到实现到测试的完整流程。这个过程走一遍之后，你对 skill 的粒度、描述怎么写、输入输出怎么定义，都会有更具体的感知。
另外，不要追求一次写对。skill 的描述和实现都是迭代出来的。先写一个能用的版本，在实际使用中观察它什么时候被调用、什么时候不被调用、输出是否符合预期，然后针对性地调整。我自己的几个核心 skill 都改了不下十版，每一版都是被实际问题逼出来的。
最后，保持 skill 的独立性。一个 skill 尽量不要依赖另一个 skill 的内部实现，只通过明确定义的输入输出交互。这样任何一个 skill 需要替换或者升级时，影响范围都是可控的。这个原则在 skill 数量少的时候可能感觉不到好处，但等到你有几十个 skill 在跑的时候，它会帮你省下大量的排查时间。
