很多人对 Agent Skills 的第一反应是：这不就是给 AI 写一套更长的提示词吗？我一开始也这么想。直到我在一个项目里连续几天重复粘贴同样的背景说明、格式要求、输出样例，才意识到真正的问题不是模型不够聪明，而是我的工作方式一直停留在“每次临时交代一遍”。Agent Skills 真正解决的，就是这件事。
它不是把提示词变长，而是把操作经验包装成一个可复用的技能单元。你可以像搭积木一样，把一次有效对话沉淀下来，下次直接调用；也可以把自己总结的方法论变成别人能用的工具。这篇文章不预设任何基础，我会从“会用”讲到“会造”，再讲到“会排错”和“会维护”。
1. 先把 Agent Skills 和“写提示词”这件事彻底分开
1.1 你缺的不是更长的提示词，而是一个能反复调用的操作单元
很多人误以为 Agent Skills 就是“高级 Prompt 工程”，确实，两者有交集，但思考模式完全不同。
写提示词的时候，你是在和模型进行一次对话。每次对话前，你都要把背景、身份、目标、格式、限制重新交代一遍。哪怕你准备了一个很完整的模板，每次都粘贴，也会遇到几个问题：一是模板越来越长，维护成本高；二是不同场景的微调会被冲掉；三是别的同事、朋友拿到你的模板，不一定知道该在哪个地方替换内容。
Agent Skills 把这件事变成了一种“文件化、结构化”的资产。你可以把一套完整的方法论、操作步骤、输入输出格式、甚至附带的脚本放在一个技能包里。调用的时候，用户只需要说：“用某某技能，处理这份材料”，而不用重复描述背景。换句话说，提示词解决的是“一次对话的质量”，Agent Skills 解决的是“一类任务的稳定性”。
我见过一个很常见的场景：团队里几个人都在用同一个 AI 工具，但每个人让它做会议纪要的方式都不一样。有人贴整段转录稿，有人只给摘要，有人要求列表，有人要求表格。结果就是每次的输出格式都有细微差异，后续整理数据时痛苦不堪。如果团队把“会议纪要整理”做成一个标准技能，所有人调用同一个版本，格式就会稳定很多。
1.2 从 AI 助手到 Agent：技能是让 AI 从“听懂”变成“能配合执行”的关键
这里要说清楚 Agent 和单纯 AI 助手之间的差别。AI 助手通常在对话里回答问题，它的能力边界是“对话上下文”。Agent 不一样，Agent 的目的是完成一个复杂任务，它需要读文件、写文件、调用工具、按步骤执行、在过程中做决策。这时候，如果每个步骤都靠在对话里临时解释，Agent 就很难稳定。
Agent Skills 恰好是中间层。它把 Agent 在执行某一类任务时需要的“约定”固化下来，包括：
- 什么时候该启用这个技能。
- 输入应该是什么，输出应该是什么。
- 中间有哪些步骤，哪些步骤有判断分支。
- 需不需要调用外部脚本或 API。
- 有哪些特殊格式要求和示例。
可以类比成：AI 助手像一个实习生，你每次都要口头交代他怎么做；而 Agent Skills 像是一份标准作业流程卡，实习生拿到卡就能执行，不需要你每次重复。对 Agent 来说，技能不只是“指令”，更是它与外部世界交互的作业手册。
这也是“AI Skills”和“Agent Skills”经常被混用，但实际侧重点不同的原因。AI Skills 更偏向模型自身具备的能力，比如推理、总结、翻译；Agent Skills 更偏向可以被调度、被复用、被组合的能力单元。前者是一种内在能力，后者是一种外在封装。一个模型可能本身很聪明，但如果没有人把任务执行流程封装成技能，它在具体场景里很容易发挥不稳定。
1.3 为什么“会造技能”比“会用模型”更能体现 AI 协作能力
我在一些讨论里看到有人把 Agent Skills 用在人文社科混合研究方法的论文写作上，比如访谈文本编码、文献归类、研究材料整理。这些并不是代码任务，但同样需要稳定输出。这类场景更能说明问题：真正有价值的不只是“模型能回答什么问题”，而是“你能否把你对任务的理解，变成一个别人也能执行的标准化方案。”
会使用模型的人，依赖模型的即时反应。会造技能的人，则是把一次成功的反应变成一种可持续复用的生产能力。你可以把“用 AI 做事”从随机性较强的手工操作，变成标准化流程。这个转变，才是 Agent Skills 更底层的影响。
2. 会用：从运行环境到一个完整技能包的解剖
2.1 先搭一个最小运行环境，不要把时间花在复杂配置上
如果你是第一次接触 Agent Skills，最好的方法不是先读一堆文档，而是先找到一个能跑通的环境。
现在很多主流 Agent 客户端、开发框架和社区工具都支持类似能力：你把一个技能目录放到指定文件夹，在对话里通过技能名称触发，它就会自动加载。具体路径、命名方式可能因工具不同有差异，但核心思路是一致的。
我建议按这个顺序开始：
- 选一个你已经在用的、支持技能加载的客户端或框架，避免为了学习再引入额外工具。
- 新建一个技能目录，放一个最简单的技能文件进去。
- 在对话里调用这个技能，确认它能被识别。
- 输出一条测试结果，确认加载成功。
如果你用的工具还不支持技能加载，可以先找社区里常见的“技能目录格式”来理解。这里的关键不是死记某个工具的配置，而是理解一个技能包通常由哪些部分组成。等理解了结构，换任何工具都能很快上手。
2.2 拆解一个典型技能的结构：描述、指令、输入、输出、示例
一个技能包通常是一个目录，里面包含一个主描述文件和若干辅助文件。不同工具可能有不同的文件名约定，但内容层普遍包含以下信息：
- 技能名称：用于调用和识别。
- 描述：说明这个技能解决什么问题、适合什么场景、什么时候不该用。
- 触发条件：什么样的情况下应该激活这个技能。
- 输入要求：需要用户提供哪些信息，什么是必填，什么是可选。
- 执行步骤：从输入到输出的处理流程，尽量编号化。
- 输出格式：希望以什么形式返回结果，是 Markdown、JSON、表格，还是纯文本。
- 示例：至少一两个典型输入输出，帮助模型理解预期效果。
- 辅助资源：脚本、数据文件、参考文档等。
举个例子，常见的技能文件可以长这样：
# 技能名称：会议纪要整理 ## 描述 把会议录音转录稿整理成结构化会议纪要，提取决策、待办、风险和遗留问题。适合项目管理、周会复盘、跨部门沟通场景。 ## 输入要求 - 会议转录稿（必填） - 与会人员列表（可选） - 会议时间（可选） ## 执行步骤 1. 通读转录稿，识别会议主题和主要议题。 2. 提取明确提到的决策，按“时间-负责人-事项”整理。 3. 提取所有待办事项，标注负责人和截止时间。 4. 提取风险或争议点，说明当前状态。 5. 将结果按固定模板输出。 ## 输出格式 返回 Markdown 格式： ## 会议主题 ## 决策记录 ## 待办事项 ## 风险与遗留问题这里是示意结构，不是为了照抄。真正落地时，你还要补充示例，甚至写一个预处理脚本来清洗转录稿。但核心逻辑是一样的：把模型需要知道的信息尽量写清楚，减少它在执行时的自由发挥空间。
2.3 从哪几个现成技能开始练手
会造之前，先要会“读”。建议你找一些现成技能来拆解，不要只看功能，要看它靠什么机制保证输出稳定。
适合新手练手的技能类型：
- 会议纪要整理：输入边界清楚，输出格式固定，容易判断质量。
- 邮件草拟：需要理解上下文，但格式简单。
- 代码审查：如果本身有编程背景，可以理解“技能描述+参照规则”如何约束输出。
- 材料分类/打标签：适合学会如何设计输入字段和输出字段。
- 学术文献结构化整理：类似前面提到的人文社科混合研究场景，把文献摘要抽取成统一字段。
每拿到一个技能，你都该问几个问题：这个技能的服务对象是谁？它靠什么避免输出不稳定的情况？它有没有用到外部脚本？如果换一种输入格式，会不会失效？带着这些问题去读，比单纯复制粘贴高效得多。
3. 会造：把一次灵光一现变成别人能复用的技能
3.1 判断什么值得做成技能
不是所有任务都值得做成 Agent Skills。做成技能也有维护成本。我一般用这几个标准来判断：
- 重复频率高：你或你的团队至少每周会做一次。
- 输入输出边界清晰：能说清楚给什么、出什么。
- 判断逻辑相对稳定：任务的核心步骤不会三天两头变。
- 错误成本可控：即使输出不完美，也不会造成严重损失。
- 有方法论沉淀价值：你希望把这次经验变成一种可复制的能力。
如果满足其中两三条，就值得尝试。如果是一个高度依赖灵感、每次结果都要求完全个性化的一次性任务，那可能更适合直接对话，而不是做成技能。
3.2 从需求描述到结构化文件：第一个技能的完整设计思路
我建议用“会议纪要整理”作为第一个造技能的对象，因为它足够典型。需求描述可以是：每次开完会，把转录稿变成带决策、待办、风险的纪要。
然后按四步走：
- 写描述。开门见山说明技能用途。
- 定输入。明确用户需要给你什么：转录稿路径、与会人、会议时间。
- 定步骤。把处理流程拆成编号步骤，让模型按顺序执行。
- 定输出。列出固定的 Markdown 模板，并给一条填写样例。
这里有一个容易被忽略的点：要让技能自己解释自己。技能文件不是给普通用户看的注释，而是要让 Agent 在执行时自动理解。所以描述里可以写“当用户说‘把这段转成纪要’或‘整理会议记录’时，使用本技能”，这能提高触发准确率。
设计完初稿后，不要急着扩大范围。先拿一段真实的会议转录稿试一下。重点看两个地方：一是技能有没有被正确触发；二是输出格式是否完全符合预期。如果输出格式不对，就回到技能文件调整输出描述和示例。
3.3 关键字段和参数的设计思路
在造技能时，最常出问题的不是步骤不够多，而是信息不够具体。
技能描述不能太泛。比如“帮助用户整理文档”，Agent 遇到任何文档都可能触发，导致误用。更好的写法是：“当用户需要把会议转写文字整理成结构化纪要，且输入材料是会议转录稿时，使用本技能。”这样既描述了场景，也给出了触发条件。
执行步骤要尽量可验证。不要只写“提取关键信息”，要写“先识别主题句，再提取所有涉及决策的句子，标注负责人；如果负责人不明确，标记为待确认”。步骤越具体，模型发挥空间越小，输出越稳。
输入要求要区分必填和可选。有些技能没有完整输入也能工作，但输出质量会打折。你可以在技能里写清楚：“如果缺少与会人员列表，默认从转录稿中识别，并在结果中标注‘由转录稿自动识别’。”
示例不是摆设。一个示例往往比一长段描述更有用。示例要覆盖“典型输入+完整输出”的组合。如果任务有常见变体，最好给两个示例：一个标准形态，一个带异常或缺失信息。
3.4 从单技能到技能组合：把复杂流程拆成多个技能再编排
学会了造单个技能之后，下一步是组合。
假设你想用 Agent Skills 辅助论文写作，尤其是“人文社科混合研究方法”这类任务。一个完整流程可能是：文献收集、摘要结构化、访谈文本编码、数据归纳、论文大纲生成。你不需要把整个流程塞进一个技能里，更好的做法是拆成几个小技能：
- 文献摘要整理技能：输入是论文 PDF 文本，输出是结构化摘要。
- 访谈文本编码技能：输入是访谈转录稿，输出是带主题标签的片段列表。
- 大纲生成技能：输入是摘要和编码结果，输出是论文大纲。
每个技能单独测试，确保稳定后，再让 Agent 通过一个“流程编排”把它们串起来。这样做有几个好处：单个技能出错时容易定位；可以单独复用；也可以替换其中一个技能而不影响整体。这和软件工程里的“高内聚、低耦合”是同一个思路。
4. 会排错：当技能不生效时，按这个顺序查问题
4.1 定位链路：加载、输入、环境、参数、日志
很多新手第一次造技能失败，第一反应就是“这个工具不行”，或者“模型太笨”。但大多数情况下，问题不在模型，而是在技能本身。
我建议按照下面的顺序排查：
| 现象 | 优先检查的方向 |
|---|---|
| 技能完全没有被触发 | 技能文件是否放在正确目录，名称是否和调用方式一致 |
| 触发了，但输出不是预期格式 | 输出格式描述是否足够具体，示例是否完整 |
| 提示找不到文件或路径失败 | 相对路径、绝对路径、文件名拼写、权限 |
| 需要调用脚本，但报错 | 脚本依赖是否安装，脚本运行时版本是否匹配 |
| 多次调用结果不稳定 | 描述中的判断条件是否模糊，是否过度依赖模型自行发挥 |
这里最重要的是“先看现象，再一层一层向下查”。不要一上来就改技能描述，先确认技能有没有被加载。如果技能根本没被触发，后面所有步骤都是空谈。
4.2 最容易踩的坑：依赖幻觉、过拟合示例、格式混乱、维护断裂
我在实际使用中见过四类高频问题。
第一类是依赖幻觉。技能描述里写着“调用脚本进行文本清洗”，但这个脚本其实没有放进技能目录，或者依赖库没装。写技能的时候一定要想清楚：我引用的外部资源是否存在？是否可执行？是否需要版本说明？最简单的做法是，在技能文件里明确标注“需要安装 Python 3.10 及以上，依赖见 requirements.txt”。
第二类是过拟合示例。技能里只放了一个超详细示例，模型照抄了示例的形态，但遇到稍微不同的输入就不会变通。比如示例里转录稿是中文，用户给的是英文，模型可能仍然按中文结构输出。这时需要增加示例的多样性，或者在步骤里明确“不限制语言，保留原文语言”。
第三类是格式混乱。输出模板太灵活，比如写“按合适的格式整理”，模型就可能每次都换一种格式。解决方法是把输出模板写死，比如“必须返回 Markdown，包含五个二级标题，顺序不能调整”。如果你要程序化读取结果，甚至可以让技能输出 JSON 结构。
第四类是维护断裂。技能造完之后没人管，模型升级或工具更新后突然不生效。所以每次修改技能，都要同步更新示例和版本号，定期回归测试。
4.3 边界：哪些情况不适合用 Agent Skills
技能不是银弹，以下情况我不建议强行做成技能：
- 一次性任务：做完就扔，没必要封装。
- 信息实时变化、依赖最新数据：如果技能没有外部数据源，模型只能靠训练知识，容易给出过时答案。
- 高风险决策：比如医疗诊断、法律意见、金融投资建议，这些场景需要人工复核，不能只靠一个自动技能直接输出结论。
- 需要强随机创意：比如头脑风暴、写小说开头，技能化反而会限制创意的多样性。
判断标准很简单：技能的价值在于“稳定复用”，如果一个任务需要高度个性化、频繁变更或者高风险决策，那它更适合在对话里临时处理，而不是固化成语义固定的技能。
5. 会维护：技能不是写完就结束，要当成小型软件来养
5.1 命名、目录、版本、更新
很多个人技能库最后沦为“一堆没人敢动的文件”，就是因为一开始没定好规范。
我建议从第一天开始给技能定版本。不需要用复杂系统，只要在技能目录里加一个CHANGELOG.md或在主文件头部写版本号和修改日期。每次修改，都要原样保留旧示例？不需要，但至少要能说明这次改了什么。
命名上，尽量采用“动词+对象+格式”的模式，比如summarize-literature-markdown，比论文摘要工具更容易被检索。目录结构建议统一：
skills/ ├── meeting-minutes/ │ ├── SKILL.md │ ├── examples/ │ └── scripts/ └── literature-summary/ ├── SKILL.md └── examples/这套结构不是唯一标准，但一致性很重要。没有一致的结构，技能一多就没法维护。
5.2 建立最小验证集：给技能写几条测试用例
维护技能最容易被忽略的是“回归测试”。
你可以给每个技能准备一个test/目录，里面放几条典型输入，每条输入对应一份期望输出。每次修改技能后，用同样几条输入重新运行，对比结果是否偏离预期。
不需要自动化，手动跑几次也可以，关键是“有参照物”。如果没有参照，你可能只是感觉自己改得更好，实际上却破坏了之前能处理的情况。
比如会议纪要技能，测试集可以包括：
- 一段带有明确决策和待办的录音转写。
- 一段信息不完整、部分负责人缺失的转写。
- 一段包含大量口语重复、无关闲聊的转写。
每个场景跑一次，看输出是否还能保持核心格式。这就是最简单有效的回归验证。
5.3 个人技能库 vs 团队共享技能库的差异
个人用可以随意一点，技能目录放在本地，出问题自己修。但如果团队要共享技能，就得多做几件事：
- 有模板：每个技能必须包含描述、输入输出、示例、已知限制。
- 有审核：合入共享库之前，至少要有另一个人试用，确认不是只对作者自己的输入有效。
- 有反馈渠道：使用者在遇到问题后能回到技能维护者那里，而不是各自改一份。
- 有废弃机制：过时、无效的技能应该定期清理或标记弃用。
团队技能库最怕的是“一人造，多人怨”。因为写技能的人自己知道各种隐含条件，但使用者不知道。所以，团队场景下，写清楚“已知边界”比写清楚“功能优点”更重要。
6. 最后聊一个判断：为什么“会造技能”会成为 AI 协作的底层能力
6.1 从“对话”到“地图”：技能是人类经验和 AI 执行之间的接口
我们正在从“每次重新组织一次对话”走向“把经验变成一张可复用地图”。Agent Skills 就像地图上的索引，它能告诉你：在这个场景下走哪条路，路上有哪些检查点，最终以什么形式到达终点。
这套思路不仅适用于程序员，也同样适用于人文社科研究者、产品经理、运营、市场人员。只要你觉得某个任务反复出现、流程可以标准化，你就能把它封装成一个技能。它的价值不是让你少打几个字，而是让你对 AI 的使用从“随机应变”变成“有序生产”。
6.2 下一阶段的关键不是模型推理能力，而是任务的封装能力
模型推理能力会越来越强，但如果没有好的技能封装，很多任务依然无法稳定落地。因为大模型本身是不可预测的，它理解意图但不保证每次输出一致。Agent Skills 的作用就是给执行过程加上约束，让结果更可预期。
一个能熟练编写 Agent Skills 的人，和一个只会用聊天框的人，差别不是在“输入速度”上，而是在“输出稳定性”和“经验的复用能力”上。前者可以不断积累自己的技能库，后者每次都是从零开始。
6.3 给刚入门的人一个行动建议
如果你现在对 Agent Skills 还只是有个模糊概念，不要再刷更多文章了。找个你常用的 AI 工具，建一个技能目录，把一个最简单的“会议纪要”技能写出来，跑通一次。然后拆一个网上现成的技能，看看别人怎么设计的。
一个小时足够。
先用起来，再理解；再做出来，再优化。等你把第一个有点粗糙的技能真正用上，你就会发现：它也许不够完美，但已经刷新了你对 AI 协作的理解。之后的每一步，都是在把“灵光一现”变成“可复用资产”。
