前言大家好这里是程序员阿亮随着各类大模型 Agent 产品的逐步普及大模型的能力边界正在被重新定义。传统的“每次对话都复制一大段 Prompt”的方式已经无法满足工业级开发的需求。目前主流的 Agent 框架普遍采纳了Agent Skill大模型技能的概念。AI 开发正在从粗放式的“提示词工程”转向更加系统、模块化、工程化的“技能工程”。一个设计良好的 Skill能让 Agent 像经验丰富的员工一样熟悉团队的开发规范和业务逻辑而一个设计混乱的 Skill不仅会让 Agent 频繁产生幻觉还会耗费大量的上下文 Token。本文将为您拆解如何设计并编写一个高质量的 AI Agent Skill。1. 什么是 Skill它的“三层渐进式架构”简单来说Skill 是一个自成一体的功能单元。它通常以一个专属文件夹的形式存在里面包含了一个必填的说明文件以及一些可选的辅助资源说明文件SKILL.md核心文件定义触发条件、指令与工作流。脚本目录scripts/存放确定性的可执行脚本用于自动化或校验可选。参考资料references/存放详细的 API 文档、结构定义或编码规范可选。模版资源assets/用于生成的模板文件或静态资源可选。Skill 之所以比普通 Prompt 更加高效在于它采用了渐进式加载的机制元数据阶段Agent 启动时只加载所有已注册 Skill 的名称和描述。这部分内容非常少用来帮助 Agent 决策“什么时候该用哪项技能”。执行阶段当对话触发了该 SkillAgent 才会把说明文件的正文内容加载到上下文中。深层按需阶段只有在执行具体子步骤时Agent 才会按需去读取参考资料里的长文档或者执行脚本目录里的脚本。这种机制可以避免在平时占用大量的上下文窗口从而降低了 Token 开销。2. 编写高质量 Skill 的三大原则原则一元数据要精准如果元数据写得太模糊Agent 在需要时就不会调用它或者在不相关的场景下被过度触发。说明文件最上方通常是格式化的元数据name: pdf-table-extractor description: 用于从 PDF 文件中提取表格数据并转换为 Markdown 或 CSV 格式。当用户要求“解析 PDF”、“提取报表表格”或提供 PDF 文件并要求提取结构化数据时使用。命名规范采用小写字母与连字符形式。描述公式明确它能做什么以及什么时候应该用它。避免使用如“帮助处理文件”这样宽泛的表述。原则二只添加特定增量大模型已经具备了较强的基础代码能力和领域常识不要在 Skill 内部解释通用的语言语法、知名的第三方库基础用法。不要写通用的编程语言基础、行业内熟知的标准协议。专注于写您团队的专有约束、项目目录结构规约、特定的业务接口定义、公司内部的流程等。原则三能用脚本解决的绝不用 Prompt 约束让模型去进行复杂的格式校验、生成严格的 Schema、或者执行多步重复文件操作是非常不稳定的。脚本目录下的可执行脚本是“执行而不读入”的这意味着运行它们不占用大模型的上下文 Token且执行结果是确定性的。例如不要在说明文件中教 AI 怎么校验生成的 JSON 格式是否正确而应该提供一个格式校验脚本并指示 Agent 去运行该脚本检查结果。3. 常见的 5 大 Skill 设计模式根据不同的业务场景我们可以将 Skill 的内部设计归纳为以下 5 种核心模式模式名称核心定义适用场景工具包装器 (Tool Wrapper)将特定框架或 API 规范打包成 Skill仅在执行特定技术栈开发时按需加载。专用 SDK 集成、特定框架调用规范。生成器模式 (Generator)利用模版资源配合参考资料中的规范驱动 Agent 生成高一致性的内容。标准化文档生成、代码脚手架生成。评审器模式 (Reviewer)将审查流程怎么审与审查标准审什么解耦。标准独立存放在参考资料中流程写在说明文件里。安全代码审计、接口向后兼容性检查。反转交互模式 (Inversion)翻转 Agent 与用户的交互模式。Agent 先主动通过提问明确需求在信息完整前不进行实际输出。需求澄清、系统架构设计起草。流水线模式 (Pipeline)在说明文件中规定阶段性卡点强制 Agent 按顺序执行。规格驱动开发、复杂代码重构。4. 实战从零设计一个前端组件 Skill我们以开发一个前端组件 Skill 为例。我们希望 AI先问清楚设计细节。遵守我们项目的 CSS 和 TypeScript 规范。自动运行本地脚本进行语法校验。目录结构react-component-creator/SKILL.md核心说明references/coding-standards.md项目规范scripts/run-linter.sh本地校验脚本name: react-component-creator description: 用于在当前 React 项目中创建或重构组件。当用户提出新建或修改组件时触发。 # 技能React 规范化组件生成器 你将作为一个前端开发助手严格按照本项目的工程标准来创建 React 组件。 ## 阶段 1确认需求 在开始生成任何代码前你必须向用户确认以下信息 - 组件的预期交互逻辑 - 必须要接收的属性Props及其类型 ## 阶段 2编写与约束 在得到上述回答后开始创建组件。你必须遵循 1. 仅使用参考资料中定义的样式规范。 2. 每一个属性必须显式声明类型。 ## 阶段 3自动化校验 在完成组件写入后你必须执行以下命令来检验代码是否合规 ./scripts/run-linter.sh 如果脚本报错请阅读报错信息并修正代码。总结实际上我们也可以通过codex、claude去编写一些我们自己使用的skill去沉淀优化或者开源这些都是我们更好使用AI的利器。
前言大家好这里是程序员阿亮随着各类大模型 Agent 产品的逐步普及大模型的能力边界正在被重新定义。传统的“每次对话都复制一大段 Prompt”的方式已经无法满足工业级开发的需求。目前主流的 Agent 框架普遍采纳了Agent Skill大模型技能的概念。AI 开发正在从粗放式的“提示词工程”转向更加系统、模块化、工程化的“技能工程”。一个设计良好的 Skill能让 Agent 像经验丰富的员工一样熟悉团队的开发规范和业务逻辑而一个设计混乱的 Skill不仅会让 Agent 频繁产生幻觉还会耗费大量的上下文 Token。本文将为您拆解如何设计并编写一个高质量的 AI Agent Skill。1. 什么是 Skill它的“三层渐进式架构”简单来说Skill 是一个自成一体的功能单元。它通常以一个专属文件夹的形式存在里面包含了一个必填的说明文件以及一些可选的辅助资源说明文件SKILL.md核心文件定义触发条件、指令与工作流。脚本目录scripts/存放确定性的可执行脚本用于自动化或校验可选。参考资料references/存放详细的 API 文档、结构定义或编码规范可选。模版资源assets/用于生成的模板文件或静态资源可选。Skill 之所以比普通 Prompt 更加高效在于它采用了渐进式加载的机制元数据阶段Agent 启动时只加载所有已注册 Skill 的名称和描述。这部分内容非常少用来帮助 Agent 决策“什么时候该用哪项技能”。执行阶段当对话触发了该 SkillAgent 才会把说明文件的正文内容加载到上下文中。深层按需阶段只有在执行具体子步骤时Agent 才会按需去读取参考资料里的长文档或者执行脚本目录里的脚本。这种机制可以避免在平时占用大量的上下文窗口从而降低了 Token 开销。2. 编写高质量 Skill 的三大原则原则一元数据要精准如果元数据写得太模糊Agent 在需要时就不会调用它或者在不相关的场景下被过度触发。说明文件最上方通常是格式化的元数据name: pdf-table-extractor description: 用于从 PDF 文件中提取表格数据并转换为 Markdown 或 CSV 格式。当用户要求“解析 PDF”、“提取报表表格”或提供 PDF 文件并要求提取结构化数据时使用。命名规范采用小写字母与连字符形式。描述公式明确它能做什么以及什么时候应该用它。避免使用如“帮助处理文件”这样宽泛的表述。原则二只添加特定增量大模型已经具备了较强的基础代码能力和领域常识不要在 Skill 内部解释通用的语言语法、知名的第三方库基础用法。不要写通用的编程语言基础、行业内熟知的标准协议。专注于写您团队的专有约束、项目目录结构规约、特定的业务接口定义、公司内部的流程等。原则三能用脚本解决的绝不用 Prompt 约束让模型去进行复杂的格式校验、生成严格的 Schema、或者执行多步重复文件操作是非常不稳定的。脚本目录下的可执行脚本是“执行而不读入”的这意味着运行它们不占用大模型的上下文 Token且执行结果是确定性的。例如不要在说明文件中教 AI 怎么校验生成的 JSON 格式是否正确而应该提供一个格式校验脚本并指示 Agent 去运行该脚本检查结果。3. 常见的 5 大 Skill 设计模式根据不同的业务场景我们可以将 Skill 的内部设计归纳为以下 5 种核心模式模式名称核心定义适用场景工具包装器 (Tool Wrapper)将特定框架或 API 规范打包成 Skill仅在执行特定技术栈开发时按需加载。专用 SDK 集成、特定框架调用规范。生成器模式 (Generator)利用模版资源配合参考资料中的规范驱动 Agent 生成高一致性的内容。标准化文档生成、代码脚手架生成。评审器模式 (Reviewer)将审查流程怎么审与审查标准审什么解耦。标准独立存放在参考资料中流程写在说明文件里。安全代码审计、接口向后兼容性检查。反转交互模式 (Inversion)翻转 Agent 与用户的交互模式。Agent 先主动通过提问明确需求在信息完整前不进行实际输出。需求澄清、系统架构设计起草。流水线模式 (Pipeline)在说明文件中规定阶段性卡点强制 Agent 按顺序执行。规格驱动开发、复杂代码重构。4. 实战从零设计一个前端组件 Skill我们以开发一个前端组件 Skill 为例。我们希望 AI先问清楚设计细节。遵守我们项目的 CSS 和 TypeScript 规范。自动运行本地脚本进行语法校验。目录结构react-component-creator/SKILL.md核心说明references/coding-standards.md项目规范scripts/run-linter.sh本地校验脚本name: react-component-creator description: 用于在当前 React 项目中创建或重构组件。当用户提出新建或修改组件时触发。 # 技能React 规范化组件生成器 你将作为一个前端开发助手严格按照本项目的工程标准来创建 React 组件。 ## 阶段 1确认需求 在开始生成任何代码前你必须向用户确认以下信息 - 组件的预期交互逻辑 - 必须要接收的属性Props及其类型 ## 阶段 2编写与约束 在得到上述回答后开始创建组件。你必须遵循 1. 仅使用参考资料中定义的样式规范。 2. 每一个属性必须显式声明类型。 ## 阶段 3自动化校验 在完成组件写入后你必须执行以下命令来检验代码是否合规 ./scripts/run-linter.sh 如果脚本报错请阅读报错信息并修正代码。总结实际上我们也可以通过codex、claude去编写一些我们自己使用的skill去沉淀优化或者开源这些都是我们更好使用AI的利器。
