前言

大家好，这里是程序员阿亮！

随着各类大模型 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 更加高效，在于它采用了渐进式加载的机制：

1. 元数据阶段：Agent 启动时，只加载所有已注册 Skill 的名称和描述。这部分内容非常少，用来帮助 Agent 决策“什么时候该用哪项技能”。

2. 执行阶段：当对话触发了该 Skill，Agent 才会把说明文件的正文内容加载到上下文中。

3. 深层按需阶段：只有在执行具体子步骤时，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：

1. 先问清楚设计细节。

2. 遵守我们项目的 CSS 和 TypeScript 规范。

3. 自动运行本地脚本进行语法校验。

目录结构

• 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的利器。