AI Agent Skill 编写指南：从结构设计到测试迭代的实战经验

1. 为什么“写 Skill”这件事值得单独拿出来聊

很多人第一次接触 Skill 这个概念，是在 AI Agent 工具链里。你给它一段自然语言描述，它就能调用某个能力去完成一件事——查数据、跑脚本、生成文档、做格式转换。看起来很简单，但真正动手写的时候，问题就来了：为什么我写的 Skill 总是被忽略？为什么同样的需求，别人写的 Skill 一次就跑通，我的要反复调？为什么有些 Skill 换个模型就废了？

这些问题的根源，其实不在模型本身，而在于 Skill 的写法。Skill 本质上是一份“给 AI 看的说明书”，它需要同时满足两个条件：机器能解析，人也能维护。这跟写代码不一样，代码是给编译器看的，Skill 是给一个“理解力很强但注意力有限”的智能体看的。你得让它一眼就知道：什么时候该用这个 Skill、用了之后会发生什么、边界在哪里。

我前后写过几十个 Skill，覆盖数据处理、文档生成、代码辅助、格式转换这些场景，踩过的坑基本能凑成一本小册子。这篇文章就把这些经验整理出来，从结构设计到参数定义，从测试方法到常见误区，尽量讲透。不管你是刚接触 Skill 的新手，还是已经写过几个但总觉得不够顺手的开发者，应该都能从中找到能直接用的东西。

关键词里提到的 Python、R 语言、LaTeX、AI Agent 这些，其实都是 Skill 常见的落地场景。比如用 Python 写一个数据清洗 Skill，用 R 语言写一个统计分析 Skill，用 LaTeX 写一个论文排版 Skill。不同场景对 Skill 的要求不一样，但底层逻辑是相通的。下面我按实际写 Skill 的顺序来展开，从最基础的结构开始，一步步往深里走。

2. Skill 的基本结构：一份好的说明书长什么样

2.1 名称与描述：第一眼决定生死

Skill 的名称和描述是它被调用的第一道门槛。很多人在这里犯的错是：名称写得太泛，描述写得太虚。比如叫“数据处理 Skill”，描述写“用于处理数据”。这种写法等于没写，因为 AI 根本不知道你处理的是什么数据、怎么处理、什么时候该用你。

正确的做法是：名称要具体到动作和对象，描述要包含触发条件和预期结果。举个例子，如果你写的是一个把 CSV 转成 JSON 的 Skill，名称可以叫csv-to-json-converter，描述可以写“当用户需要将 CSV 格式的表格数据转换为 JSON 结构时使用，支持自定义分隔符和编码格式”。这样 AI 在判断是否调用时，就有明确的依据。

我实测下来，描述里包含“当……时使用”这个句式，调用准确率会明显提升。因为 AI 在决策时，本质上是在做模式匹配，你给它一个明确的触发场景，它就能更快地对应上。

2.2 输入参数：少即是多，但每个都要说清楚

输入参数的设计是 Skill 写作里最容易过度设计的地方。新手往往想把所有可能性都覆盖到，结果参数列表长得像一份配置文档，AI 看了直接懵。我的经验是：核心参数控制在 3 到 5 个，每个参数必须有明确的类型、是否必填、默认值、以及一个具体的示例。

举个例子，一个用于 LaTeX 编译的 Skill，输入参数可以这样设计：

这个表格看起来简单，但每个字段都有讲究。source_file给了示例路径，AI 就知道要传一个文件路径而不是文件内容。output_format给了可选值，AI 就不会乱传。clean_aux用布尔值，语义清晰。engine的默认值选了最通用的 pdflatex，同时列出了其他选项。

注意：参数说明里一定要给示例值。我试过只写“文件路径”四个字，结果 AI 有时候传相对路径，有时候传绝对路径，有时候甚至把文件内容塞进来。给了示例之后，这个问题基本消失。

2.3 执行逻辑：用自然语言写清楚每一步

Skill 的执行逻辑部分，是用自然语言描述“这个 Skill 被调用后具体做什么”。这里的关键是：步骤要可执行、可验证，避免模糊表述。比如“处理数据”这种写法就不行，得写成“读取输入文件，按行解析，过滤掉空行，将每行按逗号分割，输出为 JSON 数组”。

我习惯把执行逻辑写成有序列表，每一步都对应一个明确的动作。如果涉及条件分支，就用“如果……则……”的句式。如果涉及循环，就说明循环的终止条件。这样写出来的 Skill，AI 在执行时不容易跑偏。

还有一个细节：执行逻辑里要明确说明“不需要做什么”。比如一个格式转换 Skill，你可以写“不需要验证输入数据的业务逻辑，只做格式转换”。这样能避免 AI 过度发挥，把简单任务复杂化。

2.4 输出格式：让结果可预期

输出格式的定义经常被忽略，但它直接影响 Skill 的可用性。如果输出格式不明确，AI 可能这次返回 JSON，下次返回纯文本，再下次返回一个表格。对于调用方来说，这种不确定性是灾难性的。

我的做法是：在 Skill 里明确指定输出格式，并给出一个完整的示例。比如“输出一个 JSON 对象，包含status字段（值为 success 或 error）、data字段（转换后的数据数组）、message字段（错误信息，成功时为空字符串）”。然后附上一个示例输出：

{ "status": "success", "data": [{"name": "Alice", "age": 30}], "message": "" }

这样不管是谁调用这个 Skill，拿到结果都知道怎么解析。

3. 从场景出发：不同领域的 Skill 写法差异

3.1 数据处理类 Skill：Python 和 R 语言的分工

数据处理是 Skill 最常见的应用场景之一。Python 和 R 语言在这个领域各有优势，写 Skill 的时候要根据任务特点来选择。

Python 的优势在于通用性和生态丰富。如果你要写一个 Skill 来处理 CSV、Excel、JSON 这些格式的转换，或者做数据清洗、特征工程，Python 是首选。写这类 Skill 的时候，我建议在描述里明确说明依赖的库，比如“使用 pandas 读取 CSV 文件，使用 numpy 做数值计算”。这样 AI 在调用时就知道需要确保环境里有这些库。

R 语言的优势在于统计分析和可视化。如果你要写一个 Skill 来做 SARIMA 模型拟合、α 多样性分析、单细胞测序的 GO 富集分析，R 语言更合适。写这类 Skill 的时候，描述里要写清楚输入数据的格式要求，比如“输入一个数据框，第一列是时间序列，第二列是观测值”。因为 R 语言对数据格式比较敏感，提前说清楚能减少很多调试时间。

我踩过的一个坑是：用 Python 写了一个统计检验的 Skill，结果发现 scipy 的版本不同，API 有差异，导致 Skill 在某些环境下跑不通。后来改成在 Skill 里明确指定“使用 scipy.stats.ttest_ind，要求 scipy 版本不低于 1.7.0”，问题才解决。所以写数据处理类 Skill，依赖版本一定要写清楚。

3.2 文档生成类 Skill：LaTeX 排版的细节控制

LaTeX 是学术写作和正式文档排版的首选工具，写一个 LaTeX 相关的 Skill 能大幅提升效率。但 LaTeX 的细节很多，Skill 里必须把这些细节交代清楚。

比如一个“生成论文模板”的 Skill，你需要指定：文档类（article、report 还是 IEEEtran）、页面布局（单栏还是双栏）、标题作者机构的格式、摘要和关键词的位置、正文的字体和行距。这些如果不在 Skill 里写清楚，AI 生成的模板可能跟你的预期差很远。

我写过一个用于“将 Word 公式转为 LaTeX”的 Skill，核心逻辑是：读取 Word 文档中的公式对象，提取其 OMML 格式，然后转换为 LaTeX 代码。这个 Skill 的关键在于转换规则的完整性。我在 Skill 里列了一个映射表，把常见的 OMML 标签对应到 LaTeX 命令，比如<m:f>对应\frac，<m:sup>对应^。这样 AI 在执行时就有明确的规则可循。

还有一个实用技巧：在 Skill 里加入“编译后清理辅助文件”的步骤。LaTeX 编译会产生 .aux、.log、.out 这些文件，如果不清理，目录会越来越乱。我通常会在 Skill 的最后一步写“执行latexmk -c清理辅助文件，保留 .tex 和 .pdf”。

3.3 代码辅助类 Skill：让 AI 写出能跑的代码

代码辅助类 Skill 的目标是让 AI 生成可直接运行的代码。这类 Skill 的写法跟前面两类不太一样，重点在于约束和示例。

约束方面，要明确指定编程语言、版本、依赖库、代码风格。比如“使用 Python 3.10 以上版本，只使用标准库和 numpy，函数命名用 snake_case，每个函数必须有 docstring”。这些约束能大幅提升生成代码的可用性。

示例方面，最好在 Skill 里附上一段“正确代码”的片段。比如你要写一个“生成邻接矩阵”的 Skill，可以附上这样一段示例：

import numpy as np def build_adjacency_matrix(edges, num_nodes): """根据边列表构建邻接矩阵。""" matrix = np.zeros((num_nodes, num_nodes), dtype=int) for u, v in edges: matrix[u][v] = 1 matrix[v][u] = 1 return matrix

有了这个示例，AI 生成的代码在风格和结构上就会向它靠拢，减少后续修改的工作量。

4. 测试与迭代：怎么知道 Skill 写得好不好

4.1 用边界用例做第一轮测试

Skill 写完之后，不要急着上生产，先用边界用例测一轮。什么叫边界用例？就是那些“看起来不太正常但确实可能发生”的输入。比如空输入、超长输入、格式错误的输入、包含特殊字符的输入。

我通常会准备一组测试用例，覆盖以下几种情况：

• 正常输入：标准格式的数据，验证基本功能。
• 空输入：不传任何参数，看 Skill 是否给出合理的错误提示。
• 异常输入：传一个不存在的文件路径，看 Skill 是否优雅地报错。
• 极端输入：传一个超大的文件，看 Skill 是否有性能问题。
• 歧义输入：传一个模糊的描述，看 Skill 是否能正确理解。

实测下来，大部分 Skill 的问题都出在异常输入的处理上。比如文件不存在时直接抛异常，而不是返回一个友好的错误信息。这类问题在测试阶段发现，比在生产环境发现要好得多。

4.2 观察 AI 的实际调用行为

Skill 的测试跟普通代码测试有一个本质区别：你不仅要测 Skill 本身，还要测 AI 会不会在正确的时机调用它。有时候 Skill 逻辑没问题，但 AI 就是不用它，或者在不该用的时候用了。

我的做法是：构造几个典型的用户请求，观察 AI 的调用决策。比如你写了一个“CSV 转 JSON”的 Skill，可以试试这些请求：

• “把这个 CSV 文件转成 JSON”（应该调用）
• “帮我看看这个 CSV 文件的内容”（不应该调用，应该直接读取）
• “把这个 Excel 文件转成 JSON”（不应该调用，因为格式不匹配）

如果 AI 的调用决策不符合预期，就要回头改 Skill 的描述。通常是在描述里补充更多的触发条件和排除条件。

4.3 迭代优化的三个方向

Skill 的迭代优化，我一般从三个方向入手：

第一，收窄触发条件。如果发现 Skill 被频繁误调用，就在描述里加限制。比如“仅当输入文件扩展名为 .csv 时使用”。

第二，补充示例。如果发现 AI 对某个参数的理解有偏差，就在参数说明里加一个更具体的示例。

第三，拆分复杂 Skill。如果一个 Skill 承担了太多职责，就把它拆成多个小 Skill。比如“数据处理”可以拆成“数据读取”“数据清洗”“数据转换”三个 Skill。这样每个 Skill 的职责更单一，AI 调用起来也更准确。

提示：拆分 Skill 的时候，要注意保持 Skill 之间的衔接。可以在描述里写明“本 Skill 通常与 xxx Skill 配合使用”，帮助 AI 建立调用链。

5. 那些年我踩过的坑：常见误区与修复方案

5.1 描述太抽象，AI 根本不知道什么时候用

这是最常见的坑。我早期写过一个 Skill，描述是“用于处理文本数据”。结果 AI 几乎从不调用它，因为“处理文本数据”这个描述太宽泛了，AI 无法判断具体场景。

修复方案：把描述改成具体的动作和场景。比如“当用户需要从一段文本中提取所有电子邮件地址时使用，支持从纯文本和 HTML 中提取”。改完之后，调用率立刻上来了。

5.2 参数太多，AI 记不住

另一个坑是参数列表太长。我写过一个 Skill，有 12 个参数，结果 AI 经常漏传或者传错。后来我把参数精简到 5 个，把一些不常用的配置项改成默认值，问题就解决了。

修复方案：只保留核心参数，其他参数用默认值。如果确实需要很多配置，考虑拆成多个 Skill，或者用一个 JSON 字符串参数来承载复杂配置。

5.3 输出格式不固定，调用方无法解析

这个坑在多人协作的场景下特别致命。你写的 Skill 返回 JSON，别人写的调用代码按纯文本解析，结果就是各种报错。

修复方案：在 Skill 里强制指定输出格式，并给出完整的示例。如果输出格式可能变化，就在输出里加一个format字段，说明当前返回的是什么格式。

5.4 忽略依赖和环境要求

有些 Skill 依赖特定的库或工具，但描述里没写，导致在别的环境跑不通。比如一个用 cv2 做图像处理的 Skill，如果没写“需要安装 opencv-python”，在没装这个库的环境里就会失败。

修复方案：在 Skill 的描述或执行逻辑里，明确列出依赖项和版本要求。如果依赖较多，可以单独写一个“环境准备”章节。

5.5 没有错误处理，一出问题就崩

很多 Skill 只考虑了正常流程，没考虑异常情况。比如文件不存在、网络超时、权限不足这些情况，如果没有处理，Skill 就会直接抛异常，调用方拿到一个莫名其妙的错误。

修复方案：在 Skill 的执行逻辑里加入错误处理步骤。比如“如果文件不存在，返回错误信息‘文件未找到，请检查路径’”。这样调用方就能根据错误信息做出相应的处理。

6. 进阶技巧：让 Skill 更智能、更通用

6.1 用条件分支处理多种场景

一个好的 Skill 应该能处理多种相关场景，而不是只能做一件事。比如一个“文档转换”Skill，可以支持 Markdown 转 HTML、HTML 转 PDF、LaTeX 转 PDF 等多种转换。实现方式是在 Skill 里加入条件分支：根据输入文件的扩展名和目标格式，选择不同的转换逻辑。

这样写的好处是，AI 只需要记住一个 Skill，就能覆盖多种需求。但要注意，条件分支不能太多，否则 Skill 会变得难以维护。我的经验是，一个 Skill 覆盖 3 到 5 个相关场景比较合适。

6.2 用示例引导 AI 的输出风格

如果你对输出风格有要求，比如“代码要加注释”“文档要用学术语气”“报告要包含数据来源”，可以在 Skill 里附上一段示例输出。AI 在生成结果时，会倾向于模仿示例的风格。

我写过一个“生成数据分析报告”的 Skill，在描述里附了一段示例报告的开头：“本报告基于 2024 年 1 月至 6 月的销售数据，共包含 12,345 条记录。数据来源为内部销售系统，经过去重和异常值处理后，有效记录为 11,892 条。”有了这个示例，AI 生成的报告在语气和结构上就稳定多了。

6.3 用版本号管理 Skill 的迭代

Skill 也是代码，也需要版本管理。我习惯在 Skill 的名称或描述里加上版本号，比如csv-to-json-converter-v2。这样在迭代时，可以保留旧版本，同时测试新版本。等新版本稳定后，再逐步切换。

版本号的管理还能帮助排查问题。如果某个 Skill 突然表现异常，可以快速定位是不是最近改了版本。

6.4 多 AI 协作场景下的 Skill 设计

在多 AI 协作的场景下，Skill 的设计要考虑跨模型的兼容性。不同 AI 模型对 Skill 描述的理解可能有差异，所以描述要尽量标准化、结构化。

我的做法是：用统一的模板来写 Skill，包括名称、描述、参数、执行逻辑、输出格式、依赖项、示例这几个固定部分。这样不管哪个模型来解析，都能找到需要的信息。另外，避免使用特定模型的专有术语，用通用的表达方式。

7. 一个完整示例：从零写一个 LaTeX 编译 Skill

7.1 需求分析与参数设计

假设我们要写一个 Skill，用于编译 LaTeX 项目并清理辅助文件。这个 Skill 的典型使用场景是：用户有一个 LaTeX 项目目录，里面包含 .tex 文件和图片等资源，需要编译成 PDF，同时清理编译过程中产生的 .aux、.log 等文件。

参数设计如下：

7.2 执行逻辑的详细描述

执行逻辑按以下步骤写：

1. 检查project_dir是否存在，如果不存在，返回错误信息“项目目录不存在”。
2. 检查project_dir下是否存在main_file，如果不存在，返回错误信息“主文件未找到”。
3. 根据engine参数选择编译命令：pdflatex 对应pdflatex，xelatex 对应xelatex，lualatex 对应lualatex。
4. 在project_dir下执行编译命令，编译main_file。如果编译失败，返回错误信息，包含编译日志的最后 20 行。
5. 如果clean为 true，执行latexmk -c清理辅助文件。
6. 返回成功信息，包含生成的 PDF 文件路径。

7.3 输出格式与错误处理

输出格式定义为 JSON：

{ "status": "success", "pdf_path": "./paper/main.pdf", "message": "编译成功，辅助文件已清理" }

错误情况下：

{ "status": "error", "pdf_path": "", "message": "编译失败：Undefined control sequence \\foo" }

7.4 测试与验证

测试用例包括：

• 正常项目：编译成功，PDF 生成，辅助文件清理。
• 缺少主文件：返回“主文件未找到”。
• 编译错误：返回编译日志片段。
• 不同引擎：分别用 pdflatex、xelatex、lualatex 测试。
• clean 为 false：辅助文件保留。

实测下来，这个 Skill 在大多数 LaTeX 项目上都能稳定工作。唯一需要注意的是，如果项目使用了特殊的宏包或字体，可能需要额外的编译参数。这种情况下，可以在 Skill 里加一个extra_args参数来传递额外参数。

8. 写在最后：一些个人体会

写 Skill 这件事，说到底是在“约束”和“灵活”之间找平衡。约束太少，AI 不知道该怎么用；约束太多，Skill 又失去了通用性。我的经验是：核心逻辑要严格约束，边缘情况要留出灵活空间。

另外，Skill 的写作是一个迭代过程。第一版写出来，能跑通基本流程就行。然后通过实际使用，发现哪里不顺手，就改哪里。改个三五轮之后，Skill 的质量会有明显提升。

还有一个容易被忽略的点：Skill 的文档不仅是给 AI 看的，也是给人看的。团队里其他人要维护这个 Skill 时，清晰的描述和示例能省下大量沟通成本。所以写 Skill 的时候，不妨把它当成一份“给未来的自己看的笔记”，尽量写清楚、写完整。

最后分享一个小技巧：如果你不确定一个 Skill 该怎么写，可以先观察 AI 在没有 Skill 的情况下是怎么完成这个任务的。把它的执行步骤记录下来，整理成结构化的描述，就是一个 Skill 的雏形。这个方法我试过很多次，效果很好，尤其是对于流程比较固定的任务。