最近大半年我一直在和 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 是存放在固定目录里的一种结构化文件代理在运行时会按需读取并把它当作“操作手册”来使用。你可以把它理解成给一个很聪明但刚入职的实习生准备的工作交接文档。具体差异我整理成了对照表维度PromptSkill生命周期一次会话用户级或项目级持久存在触发方式用户主动输入代理根据任务自动检索和加载内容结构自由文本固定格式 分步骤指令 辅助资源复用性靠复制粘贴目录一放全局可调可维护性越写越长改一处动全身可拆成多个小文件逐步迭代可控性全靠模型临场发挥可以指定步骤、工具、输出格式这个对照表不是理论推导是我在实际项目里反复验证过的。早期我只用 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 的项目你就知道差距在哪里了。