最近我几乎被“agent-skills”这个词刷屏了。无论是 Claude 的官方 Skills 市场还是 Codex 的 skills 玩法又或是各个开源 Agent 框架内置的插件体系都在强调同一个概念把 Agent 的某种能力封装成一个可复用的技能包。这东西到底解决什么问题它和普通的 Prompt、Tool、插件有什么区别自己怎么从零写一个真正好用的 Skill这篇文章我会结合前端的实际场景把 Agent Skills 的来龙去脉、目录结构、开发调试、架构边界和安全底线一次讲透。先给个直观感受以前我让 AI 帮我写一个 React 组件每次都要在对话里重复贴编码规范、目录结构、测试要求然后它还可能写歪。后来我把这套东西封装成一个叫做“frontend-component-skill”的技能包Agent 在需要生成组件时自动加载这个 Skill它会自己读模板、跑校验、按规范输出。最明显的改变不是我少打了几百个字而是生成结果稳定了——同一个团队里不同人触发同一个技能产出的代码风格几乎完全一致。1. Agent Skills 是什么为什么大家都在聊1.1 从一次“教 AI 干活”的经历说起上个月我在做前端项目时发现组里同学在让 AI 写组件时反复叮嘱它“要用 TypeScript”“要用函数组件”“要有测试”“别改配置文件”。但每次结果还是不一样有时候它用 class 组件有时候忘了写 props 类型有时候把样式写在全局 CSS 里。我意识到问题不在模型能力而在上下文我们给的“做事方法”太零散模型每次都在重新揣测。后来我把这套做事方法整理成一个 Skill目录里放好 SKILL.md、指令文档、组件模板和校验脚本。Agent 检测到“生成组件”这个意图后会主动加载这个技能包按照里面的规则一步步执行。结果让人惊喜代码结构稳定测试文件自动生成连注释风格都和项目规范对齐了。这背后其实是 Agent 产品形态的一次变化以前我们和 AI 对话是靠“临时叮嘱”现在是把“长期经验”固化成一个可加载的模块。谁的经验更系统谁就能让 Agent 产出更可靠的结果。这就是 Agent Skills 最核心的价值一致性、复用性、可维护性。1.2 Skill 与 Prompt、Tool、Agent 的关系很多人会把 Skill 当成“加强版 Prompt”或者“多包了几个 Tool”实际差别很大。我用一张表来说明概念本质典型表现适合解决的问题Prompt一次性指令对话开头一大段文字单个任务的临时约束Tool可调用的外部能力搜索、读文件、执行命令让 Agent 能“动手”Skill可复用的能力封装SKILL.md 指令 模板 脚本让 Agent 按统一流程完成一类任务Agent自主规划与执行的运行体决定何时调谁、按什么顺序完成复杂目标HarnessAgent 的运行时框架上下文管理、工具注册、安全控制承载 Agent 运行的环境也就是说Tool 回答的是“能做什么”Skill 回答的是“应该怎么做”。一个 Skill 内部可以包含多个 Tool 的调用规则也可以包含提示词、模板、校验逻辑和外部脚本。它更像是把“某个领域的最佳实践”打包成一个可分发的单位让 Agent 在需要时按需加载。我在实际使用中最直观的感受单独给 Tool 列表Agent 只是一堆能力堆在那里给它挂一个 Skill它就知道在什么场景下、按什么顺序、用什么标准去调用这些能力。这也是为什么很多 Agent 框架开始把“Skills”作为一等公民来设计。1.3 为什么“Skills”是这轮 Agent 热浪的分水岭从第一性原理来看大型语言模型的能力上限受两件事制约一是模型本身的参数知识二是上下文里到底放了多少有效信息。Agent 聪明与否很大程度上取决于系统在关键节点给它灌入了什么上下文。Skill 的设计恰好踩中了这个点它让上下文不再是“一次对话里堆多少算多少”而是变成了“按需加载、用完即走”的模块。这带来两个连锁反应。第一上下文成本急剧下降。如果不做 Skill你想要保证输出质量就得把几十页规范全部塞进每次请求做了 Skill详细文档放在 resources 目录里Agent 只在需要时才读取。第二经验可以横向复制。一个人写好一个 Skill整个团队甚至整个社区都可以直接安装使用这就把“调教 AI”的成本从个体经验变成了公共资产。最近热词里反复出现“first principles deep dive”我认为放到 Skills 上也适用凡是能把“做什么”和“怎么做”分离把“怎么做”固化成可复用单元的 Agent 设计都会显著提升稳定性。这也就是为什么 Claude、Codex 以及大量开源框架都在往这个方向发力。2. 手写一个 Skill前端组件开发实战2.1 Skill 的标准目录结构不管在哪个生态里一个 Skill 本质上就是一个目录里面放描述文件和相关资产。我以自己写的“frontend-component-skill”为例目录结构长这样frontend-component-skill/ ├─ SKILL.md ├─ instructions/ │ ├─ 01-requirements.md │ └─ 02-coding-standards.md ├─ templates/ │ ├─ component.tsx.tpl │ └─ component.test.tsx.tpl ├─ scripts/ │ ├─ scaffold.sh │ └─ validate.sh └─ resources/ └─ style-guide.md这里最核心的是SKILL.md它是 Agent 的“总开关”。文件头部通常包含 YAML 元信息比如技能名称、描述、适用场景正文则是给模型看的指令说明。instructions目录放更详细的拆分指令适合按步骤拆解templates目录放代码模板保证生成结果的结构一致scripts目录放可执行脚本用于脚手架生成、代码校验等resources目录放参考文档模型在需要的时候按路径读取。为什么要把指令拆成多个文件而不是全塞进 SKILL.md因为加载上下文是有预算的。Agent 首先读取的是 SKILL.md 里的概要信息只有进入对应环节才会去读更详细的指令。如果所有内容都堆在一个文件里固然简单但会让每次调用的 token 开销变得很高而且 Agent 容易在无关信息上分心。2.2 写一份高质量 SKILL.md我见过很多新手写的 SKILL.md最大的问题就是“描述太抽象”。Agent 靠 description 判断要不要启用这个技能如果你写“生成前端组件”它很可能在任何时候都觉得相关结果频繁误触发。更好的做法是写清楚触发条件、输入要求、输出约束。下面是一份简化但可用的例子--- name: frontend-component description: 生成符合团队规范的 React 函数组件。当用户要求创建新组件、按钮、弹窗、表单或列表等 UI 模块时使用。 --- # Frontend Component Skill ## 职责 - 根据需求生成 TypeScript React 函数组件。 - 自动生成对应的测试文件。 - 更新组件索引文件如果存在。 ## 执行步骤 1. 确认组件名称和 props 类型。 2. 从 templates/component.tsx.tpl 读取模板。 3. 生成组件代码并放入 src/components/ 对应目录。 4. 从 templates/component.test.tsx.tpl 读取测试模板生成测试文件。 5. 运行 scripts/validate.sh 校验生成结果。 ## 警告 - 禁止修改 package.json、tsconfig.json 等配置文件。 - 禁止引入未在依赖列表中声明的第三方库。 - 如果需求不明确先询问用户不要猜测。这里最容易被忽略的是“警告”部分。模型在实际执行时会把“禁止做什么”看得越来越重要因为正是这些负向约束避免了很多隐蔽错误。我在实践里发现写了明确禁止项之后组件误引入外部库的概率下降了很多。2.3 模板与脚本让 Skill 可复现模板的价值我刚才提了一嘴这里展开说。如果你只给指令让模型自由发挥它每次生成的代码也许“意思对了”但格式、命名、注释风格很难统一。模板相当于给模型提供了一个骨架它只需要填肉保证了产出的一致性。以组件模板为例import React from react; export interface ${ComponentName}Props { ${props} } export function ${ComponentName}({ ${propNames} }: ${ComponentName}Props) { return ( div> 
长河君 · 2026/10/7 5:56:54 · 阅读 1.2k Agent Skills 实战：从零构建可复用技能包
最近我几乎被“agent-skills”这个词刷屏了。无论是 Claude 的官方 Skills 市场还是 Codex 的 skills 玩法又或是各个开源 Agent 框架内置的插件体系都在强调同一个概念把 Agent 的某种能力封装成一个可复用的技能包。这东西到底解决什么问题它和普通的 Prompt、Tool、插件有什么区别自己怎么从零写一个真正好用的 Skill这篇文章我会结合前端的实际场景把 Agent Skills 的来龙去脉、目录结构、开发调试、架构边界和安全底线一次讲透。先给个直观感受以前我让 AI 帮我写一个 React 组件每次都要在对话里重复贴编码规范、目录结构、测试要求然后它还可能写歪。后来我把这套东西封装成一个叫做“frontend-component-skill”的技能包Agent 在需要生成组件时自动加载这个 Skill它会自己读模板、跑校验、按规范输出。最明显的改变不是我少打了几百个字而是生成结果稳定了——同一个团队里不同人触发同一个技能产出的代码风格几乎完全一致。1. Agent Skills 是什么为什么大家都在聊1.1 从一次“教 AI 干活”的经历说起上个月我在做前端项目时发现组里同学在让 AI 写组件时反复叮嘱它“要用 TypeScript”“要用函数组件”“要有测试”“别改配置文件”。但每次结果还是不一样有时候它用 class 组件有时候忘了写 props 类型有时候把样式写在全局 CSS 里。我意识到问题不在模型能力而在上下文我们给的“做事方法”太零散模型每次都在重新揣测。后来我把这套做事方法整理成一个 Skill目录里放好 SKILL.md、指令文档、组件模板和校验脚本。Agent 检测到“生成组件”这个意图后会主动加载这个技能包按照里面的规则一步步执行。结果让人惊喜代码结构稳定测试文件自动生成连注释风格都和项目规范对齐了。这背后其实是 Agent 产品形态的一次变化以前我们和 AI 对话是靠“临时叮嘱”现在是把“长期经验”固化成一个可加载的模块。谁的经验更系统谁就能让 Agent 产出更可靠的结果。这就是 Agent Skills 最核心的价值一致性、复用性、可维护性。1.2 Skill 与 Prompt、Tool、Agent 的关系很多人会把 Skill 当成“加强版 Prompt”或者“多包了几个 Tool”实际差别很大。我用一张表来说明概念本质典型表现适合解决的问题Prompt一次性指令对话开头一大段文字单个任务的临时约束Tool可调用的外部能力搜索、读文件、执行命令让 Agent 能“动手”Skill可复用的能力封装SKILL.md 指令 模板 脚本让 Agent 按统一流程完成一类任务Agent自主规划与执行的运行体决定何时调谁、按什么顺序完成复杂目标HarnessAgent 的运行时框架上下文管理、工具注册、安全控制承载 Agent 运行的环境也就是说Tool 回答的是“能做什么”Skill 回答的是“应该怎么做”。一个 Skill 内部可以包含多个 Tool 的调用规则也可以包含提示词、模板、校验逻辑和外部脚本。它更像是把“某个领域的最佳实践”打包成一个可分发的单位让 Agent 在需要时按需加载。我在实际使用中最直观的感受单独给 Tool 列表Agent 只是一堆能力堆在那里给它挂一个 Skill它就知道在什么场景下、按什么顺序、用什么标准去调用这些能力。这也是为什么很多 Agent 框架开始把“Skills”作为一等公民来设计。1.3 为什么“Skills”是这轮 Agent 热浪的分水岭从第一性原理来看大型语言模型的能力上限受两件事制约一是模型本身的参数知识二是上下文里到底放了多少有效信息。Agent 聪明与否很大程度上取决于系统在关键节点给它灌入了什么上下文。Skill 的设计恰好踩中了这个点它让上下文不再是“一次对话里堆多少算多少”而是变成了“按需加载、用完即走”的模块。这带来两个连锁反应。第一上下文成本急剧下降。如果不做 Skill你想要保证输出质量就得把几十页规范全部塞进每次请求做了 Skill详细文档放在 resources 目录里Agent 只在需要时才读取。第二经验可以横向复制。一个人写好一个 Skill整个团队甚至整个社区都可以直接安装使用这就把“调教 AI”的成本从个体经验变成了公共资产。最近热词里反复出现“first principles deep dive”我认为放到 Skills 上也适用凡是能把“做什么”和“怎么做”分离把“怎么做”固化成可复用单元的 Agent 设计都会显著提升稳定性。这也就是为什么 Claude、Codex 以及大量开源框架都在往这个方向发力。2. 手写一个 Skill前端组件开发实战2.1 Skill 的标准目录结构不管在哪个生态里一个 Skill 本质上就是一个目录里面放描述文件和相关资产。我以自己写的“frontend-component-skill”为例目录结构长这样frontend-component-skill/ ├─ SKILL.md ├─ instructions/ │ ├─ 01-requirements.md │ └─ 02-coding-standards.md ├─ templates/ │ ├─ component.tsx.tpl │ └─ component.test.tsx.tpl ├─ scripts/ │ ├─ scaffold.sh │ └─ validate.sh └─ resources/ └─ style-guide.md这里最核心的是SKILL.md它是 Agent 的“总开关”。文件头部通常包含 YAML 元信息比如技能名称、描述、适用场景正文则是给模型看的指令说明。instructions目录放更详细的拆分指令适合按步骤拆解templates目录放代码模板保证生成结果的结构一致scripts目录放可执行脚本用于脚手架生成、代码校验等resources目录放参考文档模型在需要的时候按路径读取。为什么要把指令拆成多个文件而不是全塞进 SKILL.md因为加载上下文是有预算的。Agent 首先读取的是 SKILL.md 里的概要信息只有进入对应环节才会去读更详细的指令。如果所有内容都堆在一个文件里固然简单但会让每次调用的 token 开销变得很高而且 Agent 容易在无关信息上分心。2.2 写一份高质量 SKILL.md我见过很多新手写的 SKILL.md最大的问题就是“描述太抽象”。Agent 靠 description 判断要不要启用这个技能如果你写“生成前端组件”它很可能在任何时候都觉得相关结果频繁误触发。更好的做法是写清楚触发条件、输入要求、输出约束。下面是一份简化但可用的例子--- name: frontend-component description: 生成符合团队规范的 React 函数组件。当用户要求创建新组件、按钮、弹窗、表单或列表等 UI 模块时使用。 --- # Frontend Component Skill ## 职责 - 根据需求生成 TypeScript React 函数组件。 - 自动生成对应的测试文件。 - 更新组件索引文件如果存在。 ## 执行步骤 1. 确认组件名称和 props 类型。 2. 从 templates/component.tsx.tpl 读取模板。 3. 生成组件代码并放入 src/components/ 对应目录。 4. 从 templates/component.test.tsx.tpl 读取测试模板生成测试文件。 5. 运行 scripts/validate.sh 校验生成结果。 ## 警告 - 禁止修改 package.json、tsconfig.json 等配置文件。 - 禁止引入未在依赖列表中声明的第三方库。 - 如果需求不明确先询问用户不要猜测。这里最容易被忽略的是“警告”部分。模型在实际执行时会把“禁止做什么”看得越来越重要因为正是这些负向约束避免了很多隐蔽错误。我在实践里发现写了明确禁止项之后组件误引入外部库的概率下降了很多。2.3 模板与脚本让 Skill 可复现模板的价值我刚才提了一嘴这里展开说。如果你只给指令让模型自由发挥它每次生成的代码也许“意思对了”但格式、命名、注释风格很难统一。模板相当于给模型提供了一个骨架它只需要填肉保证了产出的一致性。以组件模板为例import React from react; export interface ${ComponentName}Props { ${props} } export function ${ComponentName}({ ${propNames} }: ${ComponentName}Props) { return ( div>