【2026最新】Agent Skills 学习手册
“最重要的不是让 AI 帮你做事，而是让 AI 学会按你的方式做事。”
生成日期：2026-08-10
阅读说明
本书面向系统学习 AI Agent 技能（Skills）工程的读者。全书采用案例驱动方式，每章都包含学习目标、操作案例、练习、检查清单和常见坑。
关于 Skills：Skills 是 Codex 等 AI 编程智能体的核心扩展机制，用 Markdown 文件写成，用于将高频任务、项目规范和团队经验固化为 Agent 可自动遵循的指令包。掌握 Skills 意味着从“临时使用”AI 升级为“系统化训练”AI，是工程化落地的关键一步。
总目录
第一部分：入门篇——认识 Skills
第 1 章：Skills 是什么
1.1 Skill 的定义与本质
1.2 Skills 与普通提示词的区别
1.3 Skills 在 Codex 生态中的位置
1.4 哪些场景适合用 Skills
第 2 章：为什么需要 Skills
2.1 重复劳动的痛点
2.2 一致性与规范性的保障
2.3 知识沉淀与团队协作
2.4 从“使用”到“训练”的跃迁
第二部分：基础篇——创建与使用 Skills
第 3 章：Skill 的目录结构与发现机制
3.1 全局与项目级 Skills 目录
3.2 SKILL.md 文件的基本格式
3.3 Skill 的自动发现与加载流程
3.4 如何让 Codex 识别你的 Skill
第 4 章：编写第一个 Skill
4.1 确定要封装的场景
4.2 编写 SKILL.md：目标、步骤、约束、完成标准
4.3 存放与验证 Skill
4.4 实战：创建一个“生成 React 组件”的 Skill
第 5 章：Skill 的触发与上下文注入
5.1 何时 Skill 会被激活
5.2 指令内容如何注入上下文
5.3 多 Skill 共存的优先级
5.4 手动引用 Skill 的方式
第三部分：进阶篇——高质量 Skill 设计
第 6 章：Skill 设计原则
6.1 单一职责与可组合性
6.2 指令的具体性与可执行性
6.3 处理异常与边界情况
6.4 利用模板和示例增强稳定性
第 7 章：Skill 的测试与调试
7.1 如何验证 Skill 的效果
7.2 常见执行偏差及修正方法
7.3 迭代更新 Skill 的工作流
7.4 避免过度工程化
第四部分：高级篇——Skills 与工作流
第 8 章：Skills 的组合与编排
8.1 一个复杂任务调用多个 Skill
8.2 Skill 之间的数据传递
8.3 使用 AGENTS.md 与 Skills 协同
8.4 实战：从 PRD 到页面生成的全流程
第 9 章：团队级 Skills 库管理
9.1 共享 Skills 的版本控制
9.2 团队规范固化到 Skills
9.3 新成员接入与知识传承
9.4 定期审视与更新机制
第五部分：专题篇——实战与生态
第 10 章：常见场景 Skill 模板
10.1 单元测试生成 Skill
10.2 代码审查 Skill
10.3 文档生成 Skill
10.4 数据库迁移 Skill
第 11 章：从 Skill 到自动化工作流
11.1 识别可自动化的重复流程
11.2 将 Skills 集成到 CI/CD
11.3 监控 Skill 执行效果与成本
11.4 未来趋势：自进化 Skills
快速参考
本书各章既可顺序学习，也可按需跳读。建议初学者从第 1 章到第 5 章顺序学习，掌握基础后再根据实际需求选择进阶章节。每章末尾的“检查清单”和“常见坑”可以帮助你快速验证学习成果、规避典型错误。
第一部分：入门篇——认识 Skills
第 1 章：Skills 是什么
1.1 Skill 的定义与本质
Skill 是一个用 Markdown 写成的指令包，存放在特定的目录结构中，Codex 在启动或执行相关任务时会自动发现并加载这些指令。它的本质是将人类的经验与偏好编码为 Agent 可遵循的标准化流程。
可以类比为：给一位能力很强但没有工作经验的实习生，配上一本详细的岗位操作手册。手册里写明了“当遇到 A 类任务时，请按步骤 1-2-3 执行，注意不要违反规则 B，完成后检查 C”。Skill 就是 Codex 的“岗位操作手册”。
1.2 Skills 与普通提示词的区别
| | |
| | |
| | |
| | |
| | |
普通提示词是你“告诉” Agent 怎么做；Skills 是你“教会” Agent 怎么做，并且它永远不会忘记。
1.3 Skills 在 Codex 生态中的位置
Codex 本身是一个强大的编码智能体，但它的“默认行为”是通用的。Skills 层在 Codex 之上，提供：
•
项目级定制：针对特定技术栈、目录结构、编码规范。
•
团队级规范：统一代码风格、测试要求、提交信息格式。
•
任务级模板：将“写单元测试”“生成 CRUD 接口”等高频操作标准化。
Skills 与 AGENTS.md（全局规则文件）互补：AGENTS.md 定义“总是遵守的规则”，Skills 定义“特定任务触发的工作流”。
1.4 哪些场景适合用 Skills
•
生成新的代码模块（组件、服务、控制器）
•
编写单元测试或集成测试
•
代码审查与修复
•
生成 API 文档或变更日志
•
数据库迁移脚本生成
•
构建与部署流程辅助
•
任何你每月重复超过 3 次且有明确步骤的任务
第 2 章：为什么需要 Skills
2.1 重复劳动的痛点
没有 Skills 时，每次让 Codex 做相似任务都需要重新描述需求、重新交代背景、重新强调规则。这不仅浪费时间，还容易遗漏关键信息，导致产出质量波动。
2.2 一致性与规范性的保障
团队中的不同成员使用 Codex 时，如果各自用自己的提示词，生成的代码风格和结构可能千差万别。Skills 将规范固化为可执行指令，确保无论谁触发，Codex 都按同一标准输出。
2.3 知识沉淀与团队协作
当资深工程师将调试技巧、架构决策、性能优化经验写入 Skill 后，这份“隐性知识”就变成了显式文档，后续成员（包括未来的自己）都能复用。Skills 是活的团队知识库。
2.4 从“使用”到“训练”的跃迁
使用 Codex 是调用工具，创建 Skills 是在训练工具。后者让 Agent 变得“更懂你”，这也是吴恩达强调的“AI 放大人的能力”的典型实践。
第二部分：基础篇——创建与使用 Skills
第 3 章：Skill 的目录结构与发现机制
3.1 全局与项目级 Skills 目录
•
全局目录：~/.codex/skills/，对所有项目生效，适合存放通用技能（如“写 Python 函数”）。
•
项目级目录：<项目根>/.codex/skills/，仅对当前项目生效，适合存放定制技能（如“按本项目规范生成 Vue 组件”）。
3.2 SKILL.md 文件的基本格式
每个 Skill 是一个文件夹，必须包含 SKILL.md。文件头部推荐包含元信息（可选的 YAML frontmatter）：
3.3 Skill 的自动发现与加载流程
Codex 启动时扫描全局和项目级 skills 目录，索引所有 SKILL.md。当用户输入匹配 triggers 或语义相近时，Codex 自动将对应 Skill 内容注入会话上下文。整个过程对用户透明。
3.4 如何让 Codex 识别你的 Skill
•
确保目录路径正确。
•
确保 SKILL.md 包含清晰的描述和触发词。
•
重启 Codex 会话或使用 /init 重新索引项目。
第 4 章：编写第一个 Skill
4.1 确定要封装的场景
选择最简单、最常做的任务，例如“为 TypeScript 函数生成 Jest 测试”。不要一开始就写复杂的大型 Skill。
4.2 编写 SKILL.md：目标、步骤、约束、完成标准
参考 3.2 的结构，用自然语言清晰描述。例如：
•
Goal：生成一个完整的测试文件，覆盖函数的主要路径和边界。
•
Steps：分析函数签名 → 设计测试用例 → 生成 *.test.ts → 运行验证。
•
Constraints：使用 describe/it 结构，避免 any 类型。
•
Done When：测试运行通过，覆盖率达到 80% 以上。
4.3 存放与验证 Skill
将文件夹放入项目级 .codex/skills/，然后打开 Codex，输入触发词（如“生成测试”），观察 Codex 是否按 Skill 执行。
4.4 实战：创建一个“生成 React 组件”的 Skill
直接操作：新建文件夹 react-component-generator，编写 SKILL.md，包含组件文件、样式文件、测试文件的生成步骤和规范，保存后即生效。
第 5 章：Skill 的触发与上下文注入
5.1 何时 Skill 会被激活
•
用户输入中包含 triggers 中的关键词。
•
Codex 根据语义判断当前任务与 Skill 描述匹配。
•
用户明确要求“使用 XXX Skill”。
5.2 指令内容如何注入上下文
一旦触发，Codex 会将 SKILL.md 的全部内容（或部分摘要）追加到系统提示中，作为当前任务的“强制约束”。这意味着 Skill 中的每一步都会被优先遵循。
5.3 多 Skill 共存的优先级
当多个 Skill 同时匹配时，Codex 会根据描述的相关性、触发词的精确度和文件修改时间综合判断。你也可以通过命名规范（如 _priority 后缀）来影响排序。
5.4 手动引用 Skill 的方式
在对话中使用 @skill-name 可以强制加载指定 Skill，即使未触发自动匹配。例如：“@react-component-generator 帮我创建一个登录表单组件”。
第三部分：进阶篇——高质量 Skill 设计
第 6 章：Skill 设计原则
6.1 单一职责与可组合性
每个 Skill 只做一件事，避免大而全。复杂的任务可以通过多个 Skill 组合完成（见第 8 章）。
6.2 指令的具体性与可执行性
避免模糊描述（如“写好代码”），应具体到“使用 useState 管理状态，文件保存到 src/components/”。
6.3 处理异常与边界情况
在 Steps 中加入“如果...则...”分支，例如“如果缺少接口定义，请询问用户提供”。
6.4 利用模板和示例增强稳定性
在 Skill 文件夹内附带 templates/ 或 examples/，在 SKILL.md 中引用它们，让 Codex 有具体参照。
第 7 章：Skill 的测试与调试
7.1 如何验证 Skill 的效果
用同样的输入多次触发 Skill，检查输出是否稳定一致。对比有无 Skill 时的产出质量差异。
7.2 常见执行偏差及修正方法
•
如果 Codex 跳过了某些步骤，检查指令是否清晰，或拆分步骤。
•
如果违反了约束，在 Constraints 中加强语气（如“必须”“严禁”）。
7.3 迭代更新 Skill 的工作流
每次观察到不符预期的行为，立即更新 SKILL.md，而不是临场纠正。这如同维护代码一样，持续优化。
7.4 避免过度工程化
不要为“一次性任务”创建 Skill，只针对真正高频、标准化的操作。Skills 是需要维护成本的。
第四部分：高级篇——Skills 与工作流
第 8 章：Skills 的组合与编排
8.1 一个复杂任务调用多个 Skill
例如“生成一个完整的数据管理页面”可分解为“API 生成 Skill + 表格组件 Skill + 表单验证 Skill”。
8.2 Skill 之间的数据传递
由于每个 Skill 是独立的指令包，中间的产出（如生成的文件路径）可以通过上下文自然传递，或者在一个 Skill 中显式引用另一个。
8.3 使用 AGENTS.md 与 Skills 协同
AGENTS.md 定义全局规则（如“禁用 any 类型”），Skills 定义具体任务的流程。两者互补，共同形成完整的 Agent 行为约束。
8.4 实战：从 PRD 到页面生成的全流程
设计一个 Skill 组合链：PRD 解析 Skill → 界面结构 Skill → 前端代码生成 Skill → 测试 Skill。每个环节的输出作为下一个的输入。
第 9 章：团队级 Skills 库管理
9.1 共享 Skills 的版本控制
将全局 Skills 目录或项目级目录纳入 Git 管理，与代码一同版本化。
9.2 团队规范固化到 Skills
将团队的编码规范、Git 提交格式、代码审查清单写成多个 Skills，每位成员在自己的环境中启用。
9.3 新成员接入与知识传承
新成员只需安装 Codex 并同步 Skills 库，即自动获得团队的最佳实践，无需反复讲解。
9.4 定期审视与更新机制
建议每季度召开一次“Skills 评审会”，淘汰过时的，合并相似的，补充新的场景。
第五部分：专题篇——实战与生态
第 10 章：常见场景 Skill 模板
10.1 单元测试生成 Skill
提供函数源码，自动生成对应测试文件，包含正常路径、异常路径和边界用例。
10.2 代码审查 Skill
基于变更文件列表，检查编码规范、潜在 bug、性能问题，并生成审查报告。
10.3 文档生成 Skill
解析代码注释或 JSDoc，生成 API 文档或 README 更新建议。
10.4 数据库迁移 Skill
根据实体定义的变化，生成 SQL 迁移脚本（up/down）。
第 11 章：从 Skill 到自动化工作流
11.1 识别可自动化的重复流程
将多个 Skills 串联成完整流程，例如“代码提交前自动运行测试 → 生成变更日志 → 创建 PR 描述”。
11.2 将 Skills 集成到 CI/CD
使用 Codex 的非交互模式（codex exec）在 CI 流水线中触发特定 Skill，实现自动化代码质量检查。
11.3 监控 Skill 执行效果与成本
记录每次 Skill 调用的 Token 消耗和执行时间，评估 ROI，优化指令以减少浪费。
11.4 未来趋势：自进化 Skills
随着 LLM 能力提升，Skills 可能通过反馈循环自我更新，但当前仍需人工维护。掌握 Skills 设计，就是为未来 AI 工程化打下基础。