Agent Skills详解

Skills 标志着AI应用从对话交互向任务执行的关键跃迁。

Agent Skills旨在解决通用AI只懂道理却不会干活的核心痛点

传统大模型虽能生成代码或文本，但缺乏对特定组织框架、业务流程和品牌规范的深层理解。

Agent Skills 把特定领域的操作指南、工具脚本、参考资料打包成文件夹，让大模型在需要时查找学习，然后立刻执行（本质上是规范化的提示词工程）。

 

在架构上，Skills 采用的是三层渐进式披露架构（Progressive Disclosure）

技能目录的核心是一个 SKILL.md 文件。该文件必须以 YAML Frontmatter（前置元数据）开头，其中包含 name（技能名称）和 description（技能描述）等关键元数据。在启动阶段，代理会将所有已安装技能的 name 和 description 预加载到其系统提示符中。

 

第一层：目录索引（元数据，metadata）

"目录"，包括技能名称（最多64字符）和一句话描述（最多1024字符）。

第二层：详细步骤（SKILL.md）

主体是Markdown格式的详细指令。当 Claude 判定某项技能与当前任务相关时，它才会读取该技能的完整信息并将其加载到上下文中。

第三层：参考资料（链接文件）

随着技能复杂性的增加，单个 SKILL.md 配置文件可能无法容纳所有的上下文信息，或者某些信息仅在特定场景下才相关。在这种情况下，技能可以在目录中捆绑额外的文件，并在 SKILL.md 中通过文件名引用它们。这些额外的链接文件构成了第三层（及更高层）的详细信息，Claude 可以根据需要选择性地读取。

在执行特定子任务时，会针对性获取子链接中的内容，节省token

• 各种表单填写规则（forms.md）
• 品牌视觉规范（brand-guide.pdf）
• 代码示例库（examples.py）

层级	文件	触发时机	Token 消耗量
1	SKILL.md 索引/目录（元数据） (YAML格式)	始终可见	~100
2	SKILL.md 主体手册 (Markdown格式)	技能相关时加载	~1,500+
3+	链接文件（文档、脚本、数据）	必要时加载	按需加载

 

一个 Skill 的核心是 SKILL.md（一份大提示词+说明书），它不会自己去跑像Python和JavaScript这样的代码。真正跑代码的主体仍然是 AI 的工具系统（比如Bash、code execution），Skills 只是告诉 AI：“在某一步，请用 Bash 去执行某个脚本，然后再根据结果继续推理。”

my-skill/
├── SKILL.md              # 核心提示词与指令
├── scripts/              # 可执行脚本 (Python/Bash)
├── references/           # 需加载到上下文的参考文档
└── assets/               # 静态资源与模板

• scripts/：存放 Claude 可通过 Bash 工具调用的可执行代码。包括自动化脚本、数据处理程序、验证器或代码生成器，用于执行确定性任务。
• references/：存放 Claude 在需要时会读取到上下文中的参考文档。包括 Markdown 指南、JSON Schema、API 规范、检查清单等。凡是对于 SKILL.md 来说过于冗长，但对任务执行又必不可少的文本内容，都应放入此处。
• assets/：存放 Claude 可以引用但通常不会直接加载到上下文中的静态文件。包括 HTML/CSS 模板、图片、字体或二进制文件。

编写内容：

---
name: skill-creator
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
license: Complete terms in LICENSE.txt
---


---
# 文档前置信息
---

# [简要用途说明 - 1–2 句话]

## 概述
[描述此技能的功能、使用场景及所提供的价值]

## 前置条件
[列出所需的工具、文件或上下文]

## 操作步骤

### 步骤 1：[第一步操作]
[使用祈使句给出明确指令]
[必要时提供示例]

### 步骤 2：[下一步操作]
[使用祈使句给出明确指令]

### 步骤 3：[最后一步操作]
[使用祈使句给出明确指令]

## 输出格式
[说明结果应如何组织]

## 错误处理
[当出现问题时的应对措施]

## 示例
[提供具体的使用示例]

## 相关资源
[引用随附的 scripts/、references/、assets/ 等内容]

 

 

Skills vs MCP（Model Context Protocol）

Skills 解决“怎么做”（方法论 / 工作流），MCP 解决“连到哪儿”（连接外部系统）

对比维度	Claude Skills	Model Context Protocol
设计目标	封装人类工作流和领域知识为可复用指令	为LLM调用外部工具提供统一接口
触发机制	自动检测，无需显式调用	代理通过协议显式调用函数
配置复杂度	创建文件夹和Markdown文件，无运行时服务	需部署MCP服务器，编写JSON配置
Token效率	渐进披露，初始开销极小	通常需预加载API文档，消耗数千tokens
执行环境	完全在Claude沙箱内运行	外部服务器执行，返回结果给Claude
安全模型	运行用户安装的受信任代码	通过权限控制外部资源访问
适用场景	嵌入专业知识和内部流程	连接实时数据源和遗留系统

 

参考：https://www.apframework.com/blog/essay/2025-12-14-Claude-Agent-Skills