Agent Skills简介

什么是Skills

全称是“Agent Skills”，它是一种轻量级、开放的、渐进式披露的AI提示词文档群的管理格式。帮助AI更好地按照指定的要求完成特定的工作。

它为了解决什么问题？

目前的AI虽然能力很强大，在训练的时候已经学习了人类几乎所有的知识，但是基于大模型本身的原理，还是存在下面的问题：

• AI的知识有局限性，训练它的时候虽然会将所有人类的知识教给它，但是陷于成本和获取问题，并不是每个领域的每个知识细节它都有学习过。
• AI的知识是有时效性的，它只会知道当时训练时间点上的知识，无法了解实时的知识（MCP和RAG可以一定程度解决这个问题）
• 特定任务会有专有的执行顺序和执行要点。
• 一个完整的工作，背后都会有一套SOP（标准作业流程），这是一套庞大的提示词体系文档。
• AI的上下文不能太长，基于LLM本身的注意力机制、运行成本考虑，需要合理控制AI的上下文。将所有的上下文都一股脑抛给AI，会导致输出质量急剧下降。
• 如果想要训练特定领域的模型，通过微调的方式成本和难度太高。

Skills

基于上面的问题的存在，claude提出了一种叫Agent Skills（后面简称Skills）的提示词文档管理格式，并在2025年12月16日，将这个格式作为公开标准进行了开放 Agent Skills

一个skill可以理解为一个特定工作的指导说明书，是“应该怎么做”的步骤说明书（当然从原理上来说，严格来说skills并不限制内容应该是什么）。
你可以将完成特定工作的所有：步骤、注意事项、示例、相关知识等等都集成到一个skill中。并且它支持包含脚本、多媒体资源、庞大的额外文档资源等，并在实际需要的时候执行或者载入（skill系统会自动控制上下文，按需加载）。
而这些复杂的资料、资源、脚本都会包含在一个skill文件夹中，你可以在将它们全部打包，在另一个项目或者另一台电脑上只需要导入这个文件夹就可以获得这个“技能”（skill），使复杂的工作具有极其简单的迁移性。

对比

和rules的区别

概念上和rules不同，它不是“应该遵守什么”，而更像是“应该怎么做”。
不过最核心的区别是rules是固定完整加载的，每次提问都会完整地加载到对话中，不会按照需要选择性加载、也不会逐步加载，所以rules的编写一般是全局性的规范、并且不能太多。

而skills不是一定加载的，会根据任务实际需要来加载特定skill的文档。

它和MCP的区别

MCP也是一套让AI提供额外能力的开放格式，但是MCP更专注于“工具调用”，让AI具备和外部环境交互的能力，但本身对于上下文、提示词相关的控制的特性会弱一些（或者说MCP并不专注于这些）。
MCP只是简单将所有提供的工具全部列给AI，如何使用、何时使用还是由AI在无指导的情况下自行决定。
另外MCP的开发要复杂很多，需要开发一整套服务、并且部署。而skills只是一套文件，门槛低了非常多。
而skills本质也是一套提示词，所以它也可以指导AI进行MCP的调用。

它和工作流（workflow）的区别

类似Dify、coze、n8n的工作流也能指导特定工作按照特定的顺序进行执行，但是：

• 工作流强依赖于特定平台，并没有统一标准，不同平台的工作流标准完全不同，完全无法之间迁移
• 工作流的开发依赖于特定平台能够提供的节点，约束性更强，但是限制也更多（比如很多平台的编程节点只能支持python和js）
• 工作流固定了每个节点的执行顺序和信息传递的方向，但是skill相对来说宽松了很多，可以留给AI更多自由决策的空间。
• skill本质上只是一套渐进式加载文档的协议，实际能做到的事情会更有灵活性

Skills结构

从本质上讲，技能是一个包含SKILL.md文件的文件夹。该文件至少包含元数据（例如，name 和description）以及指示智能体如何执行特定任务的指令。技能还可以包含脚本、模板和参考资料。

my-skill/
├── SKILL.md          # 必须: 说明 + metadata
├── scripts/          # 可选: 可执行的代码
├── references/       # 可选: 文档
└── assets/           # 可选: 模板, resources等

渐进式披露

skills的核心技术特点就是渐进式披露：

• 发现：初始加载给AI的资料只有每个可用skill的名称（name）和描述（description），由AI根据需要选择需要进一步加载的skill
• 激活：当AI选择了某个skill，系统才会完整加载SKILL.md文件的内容到AI上下文中。
• 执行：AI在按照指令执行的时候，如果需要进一步加载相关的引用文档或者执行绑定脚本的时候，系统才会进一步加载。

保证了AI只会了解到最小、最贴近的信息，保证了AI响应的及时性、准确性。

Skills的详细结构

一个skill是一个目录，其中至少包含一个SKILL.md文件：

skill-name/
└── SKILL.md          # 必须

其中：

• 文件夹名字就是skill的名字
• “SKILL.md”文件名必须严格一致，“SKILL”全大写，文件扩展名为“md”
• 文件夹下除了SKILL.md文件也可以添加其他文档，但从最佳实践来说，最好也是特定工作的执行步骤（这些文档就没有文件名的强制要求了）。而相关的引用的资料、脚本都应该放在子文件夹中。

还可以根据需要选择性地添加其他目录：scripts/,references/,assets/

SKILL.md 格式

文件SKILL.md必须包含YAML前置的元数据，后面是Markdown格式的详细内容。

前言（必填）

---
name: skill-name
description: A description of what this skill does and when to use it.
---

其中name和description是必须的，而其他字段是非必须的

Field	Required	约束条件
name	是的	最多64个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。
description	是的	最多 1024 个字符。非空。描述技能的效果以及何时使用。
license	不	许可证名称或捆绑许可证文件的引用。
compatibility	不	最多 500 个字符。说明环境要求（目标产品、系统软件包、网络访问等）。
metadata	不	任意键值映射，用于添加元数据。
allowed-tools	不	技能可使用的预先批准工具列表，以空格分隔。（实验性功能）

其中，由于name和description是一定加载，并且会帮助AI进行skill的选择，所以在格式和内容上会有比较严格的限制：

name

• 必须为 1 到 64 个字符
• 只能包含 Unicode 小写字母、数字和连字符 (a-z 和 -)（不过也有看到过中文的名称，感觉这个更多是规范上的约束）
• 不能以连字符开头或结尾
• 不能包含连续的连字符 (--)
• 必须与父目录名称匹配

description

• 长度必须为 1-1024 个字符
• 应描述该技能的功能以及何时使用
• 应包含有助于代理识别相关任务的具体关键词

再次强调一下：由于name和description是一定加载，并且是帮助AI进行skill选择的，所以一定要保证AI能够通过name和描述可以正确精准地把握此skill的功能，并且不会出现歧义。

比如：

Bad：

name: PDF
description: PDF助手

Good：

name: pdf-processing
description: 该工具可以从 PDF 文件中提取文本和表格，填写 PDF 表单，并合并多个 PDF 文件。当您需要处理 PDF 文档，或者用户提及 PDF、表单或文档提取时，请使用此工具。

Body

前置数据之后就应该是Markdown的正文。格式上没有严格的限制，只需要编写能帮助AI有效完成任务的内容即可。

按照最佳实践，推荐章节：

• 基本说明
• 分步说明
• 输入输出示例
• 常见边界情况和注意事项

由于SKILL.md在激活技能的时候是完整加载的，如果特定任务的描述内容较长，可以将较长的部分拆分到多个引用文件中，AI按需进一步加载。

可选目录

为了增强AI完成特定任务的能力，可以给skill添加一些额外的资源帮助其完成工作。

scripts/

包含AI可以直接执行的代码。脚本应该是：

• 脚本是完整可执行的
• 能够输出有效的错误信息（帮助AI根据信息进行错误排查）
• 优雅地处理极端情况

支持的语言并没有限制，保证AI在调用的时候能正确执行即可。常见的语言包括Python、Bash和JavaScript.

另外在SKILL中要求AI执行某个脚本的时候，一般认为AI是不会去查看此脚本的完整代码的，所以需要详细描述调用方式，让AI在不知道脚本详细的情况下正确调用脚本（也可以有效控制AI上下文的纯净性和长度）

references/

包含AI在需要时可以查阅的其他文档。

格式上没有特殊要求，但从最佳实践的角度来说，最好保持每个文件内容的简洁性。AI会按需加载，所以文件越小越精确，AI的理解能更准确。

assets/

一些静态资源，按照实际需求添加（可以理解为others文件夹），比如（不限于）：

• 模板（文档模板、配置模板）
• 图片（图表、示例）
• 数据文件（查找表、模式）

文件引用

如果要在技能文档中引用，采用Markdown的标准格式，路径采用skill根目录的相对路径：

查看 [详细指导](references/REFERENCE.md) 以了解详细

Skill示例

上面介绍了skill的基本情况，下面来实践一个skill。

比如，在某个项目有个需求：需要在访问特定网页的时候切换到指定的代理，但是在访问公网网站的时候取消这个代理。（当然，这个可以用一些代理软件实现，但这里主要是为了演示skill的能力）

首先在项目文件夹下的.claude文件夹下（我使用的是claude code，所以在这个文件夹下，其他工具请按照各自工具的目录放置）创建skills/switch-stg-network-proxy的文件夹

.claude
└── skills/
     └── switch-stg-network-proxy/
          └── SKILL.md

SKILL.md的内容为：

---
name: switch-stg-network-proxy
description: Switch system's network configuration to allow access to stg store.
---

# 切换 stg 环境的网络配置

## Overview

XXX这个App对应的下单的网站是需要特定的网络（固定IP）以及特定的网络代理配置才能够访问，但同时这个特殊的网络配置只能访问XXX的特定下单网站，无法访问其他网站，所以需要来回进行切换。
这个文档会详细描述如何进行网络配置的切换。

此技能能够帮助用户：
1. 从普通网络配置为特定的网络配置，以便能够访问下单网站。
2. 从特定网络配置切换回普通网络配置，以便能够正常访问其他网站。

## 切换为 stg 环境商店的网络配置

1. 将系统代理中http代理和https代理设置为：
  - 主机名：xxxx
  - 端口：0000

注： 这里并不是我的SKILL的原始内容，隐藏、修改了一些项目内的信息。

此时一个skill已经写好了，我们就可以在claude code中让AI调用了：

将当前网络配置为stg特定网络配置

AI会识别到可以调用skill来实现这个需求：

⏺ 我会帮你将网络配置切换到stg环境。让我先查看一下可用的技能配置。

⏺ Read(.claude/skills/switch-stg-network-proxy/SKILL.md)
  ⎿  Read 29 lines

但是似乎结果并不是我们所希望的，AI只是将需要配置的步骤给列出来了，但是并没有真正地去配置系统的设置。这是因为AI并没有和外部系统直接交互的功能，我们的文档中也没有告诉AI应该怎么去设置系统的代理。

可以采用很多的方式解决这个问题，这里采用的是编写脚本的方式。我们使用AI编写两个bash脚本来实现打开/关闭代理的功能：

你编写两个shell脚本实现上面的网络配置切换

然后我们将这两个脚本放到skill的scripts目录下面：

.claude
└── skills/
     └── switch-stg-network-proxy/
          ├── scripts/ 
               ├── restore_normal_network.sh
               └── switch_to_stg.sh
          └── SKILL.md

然后修改SKILL.md中的指令描述（生成脚本的时候，AI也生成了脚本的使用说明，修改一下就可以搬过来了）

---
name: switch-stg-network-proxy
description: Switch system's network configuration to allow access to stg store.
---

# 切换 stg 环境 商店的网络配置

## Overview

这个项目对应的下单的网站是需要特定的网络（固定IP）以及特定的网络代理配置才能够访问，但同时这个特殊的网络配置只能访问特定下单网站，无法访问其他网站，所以需要来回进行切换。
这个文档会详细描述如何进行网络配置的切换。

此技能能够帮助用户：
1. 从普通网络配置为特定的网络配置，以便能够访问下单网站。
2. 从特定网络配置切换回普通网络配置，以便能够正常访问其他网站。

## 切换为 stg 环境商店的网络配置

执行`scripts/switch_to_stg.sh`，此脚本会完成：
1. 检测网络服务(Wi-Fi)
2. 检查当前WiFi连接(建议连接到XXX)
3. 设置HTTP代理
4. 设置HTTPS代理
5. 配置代理绕过规则
6. 显示配置结果

## 从 stg 环境的网络配置切换回普通网络配置

执行`scripts/restore_normal_network.sh`，此脚本会完成：
1. 检测网络服务(Wi-Fi)
2. 显示当前代理配置
3. 关闭HTTP代理
4. 关闭HTTPS代理
5. 清除代理绕过规则
6. 验证配置已恢复

## 注意事项

。。。

## 代理配置详情

。。。

## 手动验证

### 查看当前代理设置

。。。

### 测试网络连接

。。。

## 故障排除

。。。

注： 这里的文本依然是隐去了项目相关的内容和部分描述。并不是实际的skill原文

然后再和AI沟通，就可以正常使用skill进行代理切换了：

> 帮我把当前网络切换到stg测试用的网络配置 

⏺ 我会帮你切换到 stg 测试用的网络配置。我看到项目中已经有一个专门的 skill 来处理这个任务。

> The "switch-stg-store-network-proxy" skill is running 

> The "switch-stg-store-network-proxy" skill is running 

⏺ 好的,我现在帮你执行切换到 stg 环境网络配置的脚本。

⏺ Bash(bash .claude/skills/switch-stg-store-network-proxy/scripts/switch_to_stg.sh)
  ⎿  ========================================
     切换到 stg环境网络配置
     ========================================
     … +39 lines (ctrl+o to expand)

⏺ ✓ 网络配置已成功切换到 stg 环境!

官方Skill的示例

上面演示的是最基础的Skill创建的示例，但实际上skill可以负责很复杂的工作。

官方提供了很多的skill示例，从简单到复杂，很有参考意义。

这里简单说明一下docx这个skill,它提供的是AI能够对docx格式文件的读取、修改和创建的能力。是一个相对比较复杂的skill。

相信在阅读了上面的说明后，它的目录结构应该是能看懂的。

这里要说明的是，docx skill的根目录下面的文件：

• LICENSE.txt开源协议，公开库一般都需要添加
• SKILL.md技能文件
• docx-js.md：使用js库生成docx的教程
• ooxml.md： Office Open XML 技术参考

可以看到，当技能中有部分内容过长的时候就会提成独立的文件，优化AI的上下文。

在SKILL中引用的时候也会特别说明：

SKILL.md

# Creating a new Word document

When creating a new Word document from scratch, use **docx-js**, which allows you to create Word documents using JavaScript/TypeScript.

### Workflow
1. **MANDATORY - READ ENTIRE FILE**: Read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()

这个sample中演示了如何进行复杂任务的描述：决策分支、三方库的使用、注意事项、相关资料背景等等。非常推荐大家看看，当然看其他相对简单的sample也很不错 samples

skill能做什么

官方的示例实际上已经展示了很多的skill了：

• brand-guidelines：anthropic官方设计风格说明
• canvas-design： 按照需要，创建设计理念，并在canvas上创建图片文件进行表达
• frontend-design： 创建具有独特风格、生产级品质且设计精良的前端界面。
• mcp-builder： 帮助创建高质量的 MCP（模型上下文协议）服务器
• skill-creator： 创建有效skills的指南

等等

可以看到，因为skill只是提示词，应用可以非常广泛，包括给上下文添加设计风格的说明。
甚至skill本身也是可以自举的（即自己创建自己）

除了官方这些示例之外，也有公开的的skill集： awesome-claude-skills，它会更加多样、更加充满想象力。
(这只是其中一个开源仓库，由于这个只是一个开源协议，还会有很多其他地方可以找到skills)

Android adb控制器： 告诉AI如何使用adb和android设备进行交互。

这里只列出了一部分，大家可以进网站查看更详细的内容。

使用方式：下载对应技能的完整文件夹，放到claude code工作目录的.claude/skills目录下即可。

总结

就格式来说，skills是比较简单的。但是正是这种“简单”，降低了每个人编写skill的难度，也给skill提供了非常大的自由度。可以说用精巧得设计，解决了很多的痛点。

生产过程中的各种标准化流程，之前很难让AI遵守，现在可以了；流程中的部分步骤需要执行脚本，而不是完全由AI生成，现在可以了；和AI互动的流程很难分享给别人，现在可以了。

一个标准化的AI模型+一系列skills的组合，就能搭建出一套标准化的自动工作流。

可以说skills和MCP一样，都是非常有潜力的。
但是目前对skills的支持还比较有限，claude code算是支持最好的，codex只是实验性地支持；其他的模型和工具截至目前（2026年1月8日），还没有对skills的明确支持。所以要尝试skills还是要用claude code。

期待未来能看到更丰富的应用。