第一章Agent Skills 概述1.1 什么是 Agent SkillsAgent Skills智能体技能是 Anthropic 推出的开放标准能力扩展机制用于将特定任务的指令、脚本和参考资源封装成可复用的能力包供 AI 智能体按需加载和执行。简单来说Skill 就是一个教 AI 怎么干活的「技能手册」。它让 AI 从“会聊天”变成“会做事”。核心定义Agent Skills 是模块化的、可复用的能力扩展包专为通用 AI Agent如 Claude Code、Cursor 等设计。每个 Skill 打包了完整的“做事方法”包括任务指导指令、执行流程、最佳实践、可选的代码脚本、参考文档、素材资源等。1.2 为什么需要 Agent Skills使用 AI 时常见的一个大问题是上下文膨胀——给 AI 提供了过多的信息导致其难以完成任务。Agent Skills 通过以下方式解决此问题特征说明按需加载智能体仅在任务匹配时加载对应 Skill避免无关指令占用上下文窗口可复用同一 Skill 可在不同会话、不同任务中反复使用无需重复编写指令可版本化以文件形式存储在代码仓库中支持 Git 版本管理、Code Review 和团队协作可组合多个 Skill 可协同工作智能体根据任务需要动态调度和组合1.3 Skills 与其他技术的区别技术本质作用范围持久性Prompts对话级指令单次任务临时Agent Skills领域知识包可复用能力持久化MCP工具连接协议外部系统对接持久化用软件架构来理解应用层Agent Skills领域知识、工作流、最佳实践传输层MCP标准化接口、工具调用基础设施层数据库、API、文件系统如果说 MCP 为智能体提供了“手”来操作工具那么 Skills 就提供了“操作手册”或“SOP”教导智能体如何正确使用这些工具。第二章Agent Skills 的核心机制——渐进式披露Agent Skills 最核心的创新是渐进式披露Progressive Disclosure的三层加载机制第一层发现阶段~100 tokens智能体启动时仅加载所有技能的元数据namedescription。这部分常驻上下文用于判断“这个任务需不需要用我”。这意味着你可以安装 20 个技能包AI 启动时每个只占约 100 tokens。第二层激活阶段 5000 tokens当用户消息与元数据匹配时智能体加载完整的SKILL.md指令文档。第三层执行阶段按需加载按需动态访问引用的脚本scripts/、参考文档references/和资源文件assets/。脚本只执行不进上下文输出结果才进入上下文。运行流程示例用户发任务 → Agent 匹配 Level 1 元数据 → 决定调用 Skill → 加载 Level 2 指令 → 根据指令规划 → 按需调用 Level 3 资源/脚本 → 执行 → 观察结果 → 循环直到完成。第三章Skill 的文件结构每个 Skill 以独立目录的形式组织遵循 Agent Skills 规范。3.1 标准目录结构my-skill/ ├── SKILL.md # 必选主文件包含元数据与执行指令 ├── scripts/ # 可选可执行代码Python、Bash、JS等 ├── references/ # 可选参考文档、规范、知识材料 └── assets/ # 可选模板、图片、配置文件等静态资源3.2 SKILL.md 文件详解SKILL.md是唯一必选文件由元数据和正文两部分组成。元数据YAML Frontmatter必须包含name和description字段---name:code-reviewerdescription:Review code for security issues and best practices. Use when user asks for code review.---name技能的唯一标识符description适用场景与触发条件智能体据此判断是否加载该 Skill正文Markdown 指令分步描述操作流程可包含条件分支、检查点和预期输出并定义明确的成功标准。建议不超过 500 行。3.3 完整示例以下是一个完整的代码审查 Skill 示例--- name: code-reviewer description: Review code for security issues and best practices. Use when user asks for code review. --- # Code Review Skill ## Instructions 1. 检查常见安全漏洞SQL 注入、XSS、命令注入等 2. 评估性能问题和代码异味 3. 检查代码风格一致性 4. 给出具体的改进建议和代码示例 ## Output Format 每个问题按以下格式输出 - **Severity**: Critical / High / Medium / Low - **Location**: 文件名:行号 - **Issue**: 问题描述 - **Fix**: 修复建议 ## Examples 输入: Review this Python function for security issues 输出: 按格式给出安全审查报告第四章如何创建和使用 Agent Skills4.1 创建 Skill方式一手动创建在项目目录下创建.agents/skills/文件夹为每个 Skill 创建一个子文件夹在子文件夹中创建SKILL.md文件可选添加scripts/、references/、assets/子文件夹方式二使用 AI 辅助生成以 Cursor 为例打开 Cursor 设置 → 选择 Rules、Skills、Subagents 标签页点击新建 Skill在对话框中输入需求描述例如“根据需求文档生成测试用例需要覆盖正向、逆向、异常、并发场景”AI 会自动生成技能草稿并写入SKILL.md与 AI 交互调整细节输出格式、语言等4.2 安装 Skill使用 skills.sh CLI推荐Vercel 构建的 skills.sh 是 Agent Skills 的目录平台npx skillsaddowner/repo系统会引导你完成整个流程。安装官方技能示例安装 Flutter 技能npx skillsaddflutter/skills--skill*--agentuniversal安装 Dart 技能npx skillsadddart-lang/skills--skill*--agentuniversal4.3 使用 Skill安装好 Skill 后兼容的 AI 智能体会自动发现并使用它们。如果系统未自动触发可以直接告诉 LLM 使用特定 Skill“使用 [技能名称] 技能在项目中实现 [具体任务]”第五章最佳实践5.1 Metadata元信息设计原则Metadata 是技能的“说明书 合同 配置入口”。它回答这个 Skill 叫什么解决什么问题输入/输出是什么结构成功标准是什么有哪些风险与边界没有 Metadata 的 Agent通常会变成“写得很好但不可控”。5.2 Instruction指令设计原则Instruction 是技能的“操作系统”应该是可执行的 SOP先澄清哪些信息缺什么就问什么什么情况下必须检索什么情况下不该检索工具如何选择、调用顺序是什么、失败怎么兜底结果如何验证、冲突证据如何处理输出格式、引用规范、口吻要求最终如何自检与验收5.3 Resources资源管理scripts/存放可自动执行的脚本Agent 直接运行结果进入上下文references/存放深度参考资料、字段说明、决策表等assets/存放示意图、模板、CSV 等静态资源5.4 开发要点SKILL.md正文建议不超过 500 行元数据中的description要足够明确确保智能体能准确判断触发时机复杂任务可拆分为多个子技能文档独立加载遵循最小权限原则Skill 仅提供操作指引不能替代运行时环境与权限策略第六章高级主题6.1 Skills 与 MCP 的协同MCP 提供了原始的机械工具而 Agent Skills 提供了正确操作这些机械工具的专业知识。两者可以协同工作Skills 定义“做什么、怎么做”MCP 负责“调用什么工具”。6.2 技能的市场与生态skills.shVercel 构建的技能目录平台官方仓库Flutter 团队维护 flutter/skills 和 dart-lang/skills社区贡献GitHub 上已有大量开源技能可供参考和使用6.3 安全注意事项Agent Skills 是快速编写但难以在部署前验证的。需要建立完善的权限模型和安全审查机制遵循最小权限原则。B. 术语表术语说明Agent Skills可复用的能力扩展包包含指令、脚本和资源SKILL.md技能的核心文件包含元数据和执行指令渐进式披露按需加载信息的三级机制MCP模型上下文协议用于工具连接上下文窗口LLM 的工作记忆有 token 限制 Agent Skills 介绍与学习
第一章Agent Skills 概述1.1 什么是 Agent SkillsAgent Skills智能体技能是 Anthropic 推出的开放标准能力扩展机制用于将特定任务的指令、脚本和参考资源封装成可复用的能力包供 AI 智能体按需加载和执行。简单来说Skill 就是一个教 AI 怎么干活的「技能手册」。它让 AI 从“会聊天”变成“会做事”。核心定义Agent Skills 是模块化的、可复用的能力扩展包专为通用 AI Agent如 Claude Code、Cursor 等设计。每个 Skill 打包了完整的“做事方法”包括任务指导指令、执行流程、最佳实践、可选的代码脚本、参考文档、素材资源等。1.2 为什么需要 Agent Skills使用 AI 时常见的一个大问题是上下文膨胀——给 AI 提供了过多的信息导致其难以完成任务。Agent Skills 通过以下方式解决此问题特征说明按需加载智能体仅在任务匹配时加载对应 Skill避免无关指令占用上下文窗口可复用同一 Skill 可在不同会话、不同任务中反复使用无需重复编写指令可版本化以文件形式存储在代码仓库中支持 Git 版本管理、Code Review 和团队协作可组合多个 Skill 可协同工作智能体根据任务需要动态调度和组合1.3 Skills 与其他技术的区别技术本质作用范围持久性Prompts对话级指令单次任务临时Agent Skills领域知识包可复用能力持久化MCP工具连接协议外部系统对接持久化用软件架构来理解应用层Agent Skills领域知识、工作流、最佳实践传输层MCP标准化接口、工具调用基础设施层数据库、API、文件系统如果说 MCP 为智能体提供了“手”来操作工具那么 Skills 就提供了“操作手册”或“SOP”教导智能体如何正确使用这些工具。第二章Agent Skills 的核心机制——渐进式披露Agent Skills 最核心的创新是渐进式披露Progressive Disclosure的三层加载机制第一层发现阶段~100 tokens智能体启动时仅加载所有技能的元数据namedescription。这部分常驻上下文用于判断“这个任务需不需要用我”。这意味着你可以安装 20 个技能包AI 启动时每个只占约 100 tokens。第二层激活阶段 5000 tokens当用户消息与元数据匹配时智能体加载完整的SKILL.md指令文档。第三层执行阶段按需加载按需动态访问引用的脚本scripts/、参考文档references/和资源文件assets/。脚本只执行不进上下文输出结果才进入上下文。运行流程示例用户发任务 → Agent 匹配 Level 1 元数据 → 决定调用 Skill → 加载 Level 2 指令 → 根据指令规划 → 按需调用 Level 3 资源/脚本 → 执行 → 观察结果 → 循环直到完成。第三章Skill 的文件结构每个 Skill 以独立目录的形式组织遵循 Agent Skills 规范。3.1 标准目录结构my-skill/ ├── SKILL.md # 必选主文件包含元数据与执行指令 ├── scripts/ # 可选可执行代码Python、Bash、JS等 ├── references/ # 可选参考文档、规范、知识材料 └── assets/ # 可选模板、图片、配置文件等静态资源3.2 SKILL.md 文件详解SKILL.md是唯一必选文件由元数据和正文两部分组成。元数据YAML Frontmatter必须包含name和description字段---name:code-reviewerdescription:Review code for security issues and best practices. Use when user asks for code review.---name技能的唯一标识符description适用场景与触发条件智能体据此判断是否加载该 Skill正文Markdown 指令分步描述操作流程可包含条件分支、检查点和预期输出并定义明确的成功标准。建议不超过 500 行。3.3 完整示例以下是一个完整的代码审查 Skill 示例--- name: code-reviewer description: Review code for security issues and best practices. Use when user asks for code review. --- # Code Review Skill ## Instructions 1. 检查常见安全漏洞SQL 注入、XSS、命令注入等 2. 评估性能问题和代码异味 3. 检查代码风格一致性 4. 给出具体的改进建议和代码示例 ## Output Format 每个问题按以下格式输出 - **Severity**: Critical / High / Medium / Low - **Location**: 文件名:行号 - **Issue**: 问题描述 - **Fix**: 修复建议 ## Examples 输入: Review this Python function for security issues 输出: 按格式给出安全审查报告第四章如何创建和使用 Agent Skills4.1 创建 Skill方式一手动创建在项目目录下创建.agents/skills/文件夹为每个 Skill 创建一个子文件夹在子文件夹中创建SKILL.md文件可选添加scripts/、references/、assets/子文件夹方式二使用 AI 辅助生成以 Cursor 为例打开 Cursor 设置 → 选择 Rules、Skills、Subagents 标签页点击新建 Skill在对话框中输入需求描述例如“根据需求文档生成测试用例需要覆盖正向、逆向、异常、并发场景”AI 会自动生成技能草稿并写入SKILL.md与 AI 交互调整细节输出格式、语言等4.2 安装 Skill使用 skills.sh CLI推荐Vercel 构建的 skills.sh 是 Agent Skills 的目录平台npx skillsaddowner/repo系统会引导你完成整个流程。安装官方技能示例安装 Flutter 技能npx skillsaddflutter/skills--skill*--agentuniversal安装 Dart 技能npx skillsadddart-lang/skills--skill*--agentuniversal4.3 使用 Skill安装好 Skill 后兼容的 AI 智能体会自动发现并使用它们。如果系统未自动触发可以直接告诉 LLM 使用特定 Skill“使用 [技能名称] 技能在项目中实现 [具体任务]”第五章最佳实践5.1 Metadata元信息设计原则Metadata 是技能的“说明书 合同 配置入口”。它回答这个 Skill 叫什么解决什么问题输入/输出是什么结构成功标准是什么有哪些风险与边界没有 Metadata 的 Agent通常会变成“写得很好但不可控”。5.2 Instruction指令设计原则Instruction 是技能的“操作系统”应该是可执行的 SOP先澄清哪些信息缺什么就问什么什么情况下必须检索什么情况下不该检索工具如何选择、调用顺序是什么、失败怎么兜底结果如何验证、冲突证据如何处理输出格式、引用规范、口吻要求最终如何自检与验收5.3 Resources资源管理scripts/存放可自动执行的脚本Agent 直接运行结果进入上下文references/存放深度参考资料、字段说明、决策表等assets/存放示意图、模板、CSV 等静态资源5.4 开发要点SKILL.md正文建议不超过 500 行元数据中的description要足够明确确保智能体能准确判断触发时机复杂任务可拆分为多个子技能文档独立加载遵循最小权限原则Skill 仅提供操作指引不能替代运行时环境与权限策略第六章高级主题6.1 Skills 与 MCP 的协同MCP 提供了原始的机械工具而 Agent Skills 提供了正确操作这些机械工具的专业知识。两者可以协同工作Skills 定义“做什么、怎么做”MCP 负责“调用什么工具”。6.2 技能的市场与生态skills.shVercel 构建的技能目录平台官方仓库Flutter 团队维护 flutter/skills 和 dart-lang/skills社区贡献GitHub 上已有大量开源技能可供参考和使用6.3 安全注意事项Agent Skills 是快速编写但难以在部署前验证的。需要建立完善的权限模型和安全审查机制遵循最小权限原则。B. 术语表术语说明Agent Skills可复用的能力扩展包包含指令、脚本和资源SKILL.md技能的核心文件包含元数据和执行指令渐进式披露按需加载信息的三级机制MCP模型上下文协议用于工具连接上下文窗口LLM 的工作记忆有 token 限制