Agent Skills实战：从提示词到可复用技能包，打造稳定高效的AI代理

最近大半年，我一直在和 agent 开发较劲。手上同时在用 Claude Code、Codex 和几个开源的 agent 框架，慢慢发现一个规律：真正决定 agent 好不好用的，往往不是模型本身，而是你有没有给它准备一套拿得出手的 agent skills。很多人把 skills 理解成高级 prompt，其实差得很远。Skills 是一套可以让代理在运行时按需检索和执行的技能包，它的设计目标，就是把那些重复性、强流程性的任务固化成标准操作手册，让 agent 不用每次从头理解。这篇文章我会从概念对比讲起，再带你手写一个前端开发 skills，并分享安装、调试、评测的一整套实操流程，适合正在折腾 agent 开发，或者刚接触 Claude Code、Codex 这类工具的同学直接照着做。

1. 从“提示词”到“技能包”：agent skills 到底在解决什么问题

1.1 先搞清楚 skill 和 prompt 的本质区别

经常有人跑来问我，直接写 prompt 不就行了，为什么还要搞 skills？我的回答是：prompt 是一次性的，skills 是可复用的。区别不在文字长短，而在结构和生命周期。

prompt 本质上是你在会话开始时塞给模型的一段上下文，它会跟你的问题一起进入模型窗口。你换个对话、换一个项目，这段 prompt 就失效了，所有上下文得重新组织。而 skills 是存放在固定目录里的一种结构化文件，代理在运行时会按需读取，并把它当作“操作手册”来使用。你可以把它理解成给一个很聪明但刚入职的实习生准备的工作交接文档。

具体差异我整理成了对照表：

这个对照表不是理论推导，是我在实际项目里反复验证过的。早期我只用 prompt 管理前端项目的开发规范，结果每开一个新任务，我都要把需求背景、技术栈、代码风格、目录结构这些信息重新交代一遍，模型还是经常跑偏。后来我把这些内容拆成几个 skills，代理会自动找到对应的技能目录并加载，稳定性明显提升。

1.2 harness 和 agent 各管哪一段

聊 skills 之前，有一个概念必须先理清：harness 和 agent 的分工。这个词组在网上经常出现，但很多教程一笔带过，导致新手一直搞不清楚技能到底装在哪个环节。

其实很好理解。harness 是底层框架，负责上下文管理、工具调用、执行循环、权限控制这些基础设施；agent 是决策中枢，在 harness 上面做推理、规划、修正动作。Skill 则处于两者之间，是一种特殊的领域知识包，让 agent 在面对具体任务时能快速调用内部沉淀的方法论。

我常用一个比喻：harness 是车架和发动机，agent 是司机，skills 是司机随身携带的驾驶手册和工具箱。踩油门、打方向盘这种基础操作由 harness 负责；去哪里、走哪条路是 agent 的决策；而遇到窄路会车、雨天路面湿滑该怎么处理，靠的是老司机脑子里的技能记忆。你不能把一套完整的道路理论塞进每一次对话，但你可以把关键操作标准写成技能文件，让 agent 随时翻阅。

这个区分很关键。如果你发现代理经常“自作主张”，问题是 agent 的决策逻辑；如果你发现代理有能力但执行松散、步骤混乱，那大概率是 harness 与 skills 的衔接出了问题，而不是模型本身不行。

1.3 为什么你的代理需要一个“技能目录”

很多人刚开始用 agent 会觉得“这家伙怎么那么笨，明明给过信息却总是忘”。其实不是它笨，而是你没给它一个固定的知识组织方式。每次会话结束后，模型不会保留任何记忆，所有上下文都要重新构造。如果你只是把一堆要求写在聊天里，下一轮对话就烟消云散了。

技能目录存在的意义，就是把经验沉淀成文件资产。打个比方，如果你带团队，你不会每次开会都把公司规章制度从头到尾念一遍，你会让大家自己去查文档、看流程。Agent 也是一样。你给它一套技能目录，它就知道接到什么任务该翻什么手册。

我自己的项目里通常会有四类技能目录：一类负责编码规范，一类负责自动化脚本，一类负责文档生成，还有一类专门处理项目特有的业务逻辑。这样划分之后，大部分常规任务根本不需要我操心，代理自己会去合适的地方找答案。

2. 一个标准技能长什么样：目录结构、SKILL.md 与辅助资源

2.1 SKILL.md 的写法：前面交代任务，后面给代理当工作手册

现在很多 agent 框架都沿用了统一的概念：每个技能一个独立目录，目录里必须有一个 SKILL.md 作为入口。这个文件格式很有讲究，开头是 YAML 格式的元信息，后面是 Markdown 格式的正文。

先说 YAML 部分。至少要有 name 和 description 两项。description 尤其重要，因为代理会根据任务语义来匹配技能描述，描述写得太泛，代理会频繁误加载；写得太窄，又容易漏掉。最好的做法是描述里明确“这个技能解决什么问题”“在什么场景下使用”，甚至可以给几个典型任务示例。有些框架还支持指定 allowed-tools，也就是这个技能运行时允许调用哪些工具。这个字段我建议尽量收紧，避免代理凭技能里的指令去执行不相关的外部操作。

正文部分才是重头戏。不要写成一篇泛泛的说明文，而要写成一份“可以照着执行的标准作业流程”。我会用四个小标题组织：任务概述、执行步骤、质量要求、边界与禁忌。执行步骤尽量用编号列表，每一条都给出具体动作和预期结果。质量要求用来约束输出，比如“所有组件必须通过 ESLint 检查”“每个函数必须有 JSDoc 注释”。边界与禁忌用来告诉代理哪些事不能做，这一块很多人会忽略，但它恰恰是避免事故的关键。

2.2 辅助资源怎么放：模板、脚本和参考文件

SKILL.md 不是唯一的文件。一个完整技能往往需要配套的资源，比如模板文件、参考文档、可执行脚本。

我建议在技能目录下再建几个子目录：scripts/ 放脚本，templates/ 放模板，references/ 放参考资料。这样代理在读取 SKILL.md 后，可以根据步骤去调用实际资源。举例来说，如果你的技能是“生成并编译一份 LaTeX 文档”，SKILL.md 里写清楚编译命令和常见错误处理，templates/ 目录里放一份现成的论文模板，scripts/ 目录放一个自动编译脚本，references/ 目录放字体、样式等规范说明。这种结构的好处是职责清晰，代理知道去哪里找什么。

我见过不少失败的案例，把模板内容直接塞进 SKILL.md，结果文件变得又臭又长，agent 读起来非常吃力。正确做法是 SKILL.md 只需要提供指引和步骤，具体的骨架代码、配置文件一律外置。这样不仅加载快，维护起来也很方便。你更新模板时，完全不用去动 SKILL.md。

2.3 我踩过的坑：命名、路径和技能膨胀

使用 skills 这一年多，我自己踩过的坑至少能列一页纸。最典型的就是“技能膨胀”。一开始我图省事，把很多相关的操作全写进一个 SKILL.md 里，比如既管前端组件生成，又管样式规范，还管代码提交信息格式。结果代理一碰到前端任务，就把这个几百行的文件整个读进去，响应速度肉眼可见地变慢，而且经常选错流程。后来我把每个技能拆到只干一件事，每个 SKILL.md 控制在五十到一百行以内，情况立刻好转。

第二个坑是路径问题。技能目录里的相对路径在不同工具里的解析方式不太一样，尤其是当技能目录被嵌套到项目里时，脚本有时会找不到模板文件。我的习惯是在 SKILL.md 开头明确写出“本技能所有相对路径均相对于该技能所在目录”，并在关键步骤里标注具体路径写法，这样能减少不少误解。

第三个坑是命名。给技能目录起名时，一定要用跟业务强相关的中文或英文短语，比如 “frontend-component-generator” 或 “latex-typesetting”。别用那种模棱两可的名字，比如 “utils” 或 “helper”，否则代理在自动检索时根本不知道这些技能是干什么用的。

3. 手把手做一个前端开发 skills：从零到可用的完整流程

3.1 先定边界：这个技能负责什么，不负责什么

我拿一个实际项目举例：做一个“React 登录表单组件生成技能”。很多人拿到这种需求会马上开始写代码，但我建议先花几分钟定义边界。

这个技能负责什么？负责根据业务要求生成一个符合团队规范的表单组件，包括表单字段、校验规则、提交逻辑、错误提示。不负责什么？不负责后端接口联调，不负责全局状态管理，不负责页面路由。边界越清晰，代理在加载技能后就越清楚自己该关注哪些内容，不会被无关信息带偏。

这一步看似简单，但对后续质量影响极大。有一次我写技能时没写“不负责后端接口”，结果代理生成组件时一直在嘲讽后端接口字段定义，把自己绕晕了。加上清晰的边界之后，它只负责前端部分，其他问题会留给调用者处理。

3.2 编写 SKILL.md：一个可复用的 React 表单组件技能示例

新建一个目录 react-form-component/，在里面创建 SKILL.md，内容大致如下：

--- name: react-form-component description: 用于生成符合团队规范的 React 表单组件。适合登录、注册、信息采集等表单场景。典型任务：“帮我生成一个登录表单”“做一块用户信息编辑表单”。 allowed-tools: - Read - Write - Edit --- # React 表单组件生成技能 ## 任务概述 本技能用于在 React + TypeScript 项目中生成表单组件。所有输出必须遵循项目现有目录规范和 ESLint 规则。 ## 执行步骤 1. 读取项目根目录的 package.json，确认 React 版本和是否使用 TypeScript。 2. 读取 src 目录下现有的表单组件，尽量复用已有样式和组件库。 3. 根据需求确定表单字段，列出字段名、类型、是否必填、校验规则。 4. 使用 react-hook-form 编写表单逻辑，字段校验使用 zod schema，避免在组件内写大量手工校验函数。 5. 输出组件文件到 src/components/ 目录，文件名为 PascalCase，例如 LoginForm.tsx。 6. 在文件头部提供使用示例注释，方便其他开发者接入。 ## 质量要求 - 所有组件必须通过 TypeScript 类型检查。 - 所有错误提示文案放置在一个统一常量文件里，不允许硬编码在 JSX 中。 - 提交按钮在表单加载或提交时自动禁用并显示 loading 状态。 ## 边界与禁忌 - 本技能不负责后端接口对接，生成的组件里所有请求逻辑均通过 props 回调函数注入。 - 不要擅自安装新的 npm 依赖，如确有需要，在最终报告中明确说明。 - 不要修改已有的全局样式文件，组件样式优先使用内联样式或局部 CSS 模块。

这个示例不是空话，它几乎每一步都是可执行指令。第 1 到第 3 步是信息采集，第 4、5 步是具体写码逻辑，质量要求和边界是给代理套上“缰绳”。写清楚之后，代理生成代码的规范程度会高很多。

3.3 安装与验证：怎么确认代理真的学会了这个技能

技能写好了，接下来是安装。不同 agent 工具的安装位置不太一样，但模式大同小异。Claude Code 通常是把技能目录放到用户配置目录下的 skills 文件夹，或者在项目根目录创建 skill 目录；Codex 也有类似的约定。对开源框架，一般是放到你自定义的 agent harness 的加载路径里。

安装完成后，马上做一个最小验证。我会输入一个非常明确的测试任务，比如“帮我生成一个包含用户名、邮箱、密码三个字段的登录表单组件”。然后重点观察两件事：第一，代理是否自动加载了 react-form-component 这个技能；第二，生成结果是否遵循了 SKILL.md 里的质量要求体现。

如果代理没有主动加载技能，通常是 description 写得不够直观，或者触发词跟任务描述不匹配。你可以把描述里的关键词改得更贴近实际任务说法，比如加“登录”“注册”“表单”这类词。

3.4 进阶：让技能可组合、可复用、可回归

单个技能做好之后，接下来要思考组合性。真正好用的技能体系不是一堆孤立的技能，而是能互相搭配的“零件”。举个例子，我可以把“生成表单验证逻辑”这个能力独立成一个更小的技能，让 react-form-component 技能在执行时也参考这个子技能。这样当我更新校验规范时，只需要改一个地方，所有跟表单相关的技能都会受益。

再一个关键点是“回归”。每次你改一个技能的 SKILL.md 内容，都可能影响它之前的稳定表现。所以我在自己的项目里会给每个技能配一个最小回归测试集，通常包含三到五个典型任务。每次修改技能后，跑一遍这些任务，看输出是否还是符合预期。这个动作看起来费时，实际能为后面省下大量调试精力。

4. 常见问题与排查技巧实录

4.1 “agent execution terminated due to error”到底是谁的锅

很多人在日志里看到 “agent execution terminated due to error” 就慌，以为是模型不行。实际上这个错误有一大半是脚本或工具调用的问题。最常见的情况是技能里的脚本中途退出，退出码非零，代理认为是致命错误，直接终止了执行。

我遇到过一回，写了一个 LaTeX 排版技能，里面调用了外部编译脚本，结果脚本没有做异常处理，一旦编译失败就直接退出。代理收到非零退出码后立刻终止，根本来不及解释原因。后来的解决方案是在脚本里加上 try-catch 和错误提示，把真正的错误信息打印出来，同时让代理可以继续尝试修复，而不是直接放弃。

排查这类问题，我建议先关掉代理的自动纠错，在日志里把每一步工具调用的输出都记录下来，定位到具体是哪一步失败。只要能看到最后执行的命令和执行结果，问题基本就能锁定。

4.2 技能装上了但代理不加载，怎么办

技能没被加载，先别急着改文件。第一步检查目录名称是否跟技能 name 字段一致，两者不一致是新手最容易犯的错。第二步看 description 里的关键词是否与实际任务相关，如果描述里全是抽象概念，代理很可能把它和别的技能混淆。第三步检查技能目录是否有读权限，某些项目仓库的目录权限过窄会导致 agent 无法读取。

还有一个经常被忽略的点：某些工具要求技能文件名字严格定为 SKILL.md，大小写不能错。如果你写成了 skill.md 或者 Skill.md，代理可能不会识别。这些细节看起来不起眼，但每一个都能浪费你半小时以上。

4.3 技能评测怎么做：用最小回归集守住质量底线

热词里经常出现 “agent evals”，很多人以为评测是研究团队才需要做的事，其实个人开发者也应该有自己的轻量评测方案。

最简单的方法就是准备一个文本文件，里面记录十个左右的典型任务，每个任务配上预期输出检查点。比如“生成登录表单”“生成注册表单”“生成重置密码表单”，每个任务的检查点分别是“包含三个字段”“包含两个字段”“包含三个字段且状态切换正确”。改动 skill 后，把这些任务依次跑一遍，记录通过率。通过率下降就说明新改动引入了 regression，需要对比之前的版本。

这套做法成本很低，但非常有效。我靠着这个回归集把一个技能从“偶尔踩线”打磨到“基本次次满意”的程度。没有评测机制，任何 agent 开发都像在盲改，出了问题都不知道是哪次改动惹的祸。

4.4 我的独家避坑清单

最后再给一份避坑清单，这些都是我实打实踩出来的经验：

• 技能目录和技能名称不要用中文文件名，不同系统之间迁移容易出问题。
• description 里的关键词要放实际用户会说的话，而不是技术名词。
• 一个技能只解决一个问题，超过一百行 SKILL.md 就要考虑拆分。
• 脚本退出码必须非零即失败，并且要在日志里给出可读的错误信息。
• 不要轻易允许技能自动联网下载依赖，尽量在边界与禁忌里禁止。
• 更新技能后建议同步更新回归集，别让测例和技能脱离。

5. 从技能包到能力系统：给不同阶段开发者的落地建议

如果你刚开始接触 agent 开发，我建议不要急着从零写技能，先到社区里找现成的技能包。superpower skills 这种打包好的项目就值得研究，它里面有不少高质量技能，你可以把它安装到自己的 agent 环境里跑一遍，看它是怎么组织目录、怎么写 description、怎么拆步骤的。然后拿着现成技能做模板，改成自己的东西，这个路径比从空白文件开始顺畅得多。

如果你有了一定基础，就可以开始自己定义技能体系了。我建议先从平时重复次数最多的任务入手，比如前端开发里的组件生成、代码审查、单元测试编写。把这些任务做成技能后，你会明显感受到 agent 的输出稳定性提高，因为你不再依赖它临场发挥，而是给了它一套可以反复执行的标准流程。

有一点我要特别提醒：技能不是越复杂越好。它本质上是对抗大模型“自由发挥”的一种约束，所以约束越多、结构越清晰，效果越好。一份好的 SKILL.md，读起来应该像一份标准作业指导书，而不是含糊其辞的散文。写完之后，多拿真实任务去跑几遍，主动换不同的措辞描述需求，看看代理能不能每次都准确命中对应的技能。跑通几轮之后，你对 skill 和 agent 的配合逻辑就会有直觉了。

我在实际使用中的体会是，agent skills 最大的价值不是让代理变得“更聪明”，而是把团队或个人积累的工作方法固化下来，让每次执行都有迹可循。随着你维护的技能数量增加，你会发现自己已经不是单纯在使用 agent，而是在建设一套属于自己的“能力操作系统”。这一步走过去之后，再回头看那些只会堆 prompt 的项目，你就知道差距在哪里了。