AI coding上手之Agent Skills 快速入门

摘要： Claude Skills 是 Anthropic 推出的模块化 AI 能力单元，通过封装特定任务的知识、流程和工具，实现 Agent 的按需专业化。其核心设计包括：模块化结构：每个 Skill 独立管理，包含元数据（YAML）、执行指南（Markdown）及可选资源（脚本/模板），支持自动匹配与动态加载。三层加载机制：优先加载轻量级元数据，触发任务时引入详细指令，按需调用深层资源，优

技术能量站

589人浏览 · 2026-03-08 13:18:12

技术能量站 · 2026-03-08 13:18:12 发布

2025 年 10 月中旬，Anthropic 正式发布 Claude Skills。两个月后，Agent Skills 作为开放标准被进一步发布，意在引导一个新的 AI Agent 开发生态。
在这里插入图片描述
OpenAI、Github、VS Code、Cursor 均已跟进。

为了更好的理解，你可以把Skills 理解为“通用 Agent 的扩展包”：

Agent 可通过加载不同的 Skills 包，来具备不同的专业知识、工具使用能力，稳定完成特定任务。
在这里插入图片描述

一、什么是Skills

1.1 Skills 核心概念

Skil 是一个模块化的、可复用的能力单元，将 Agent 完成某个特定任务所需的领域知识、操作流程、要用到的工具、以及最佳实践都封装在一起，Agent 将会适时自动加载所需 Skills。

模块化：skills 是一个个独立的文件夹，将完成特定任务所需的知识、流程和资源打包在一起。每个 Skil 做一件事，比如“生成PPT”是一个 Skil，"审校文章"是另一个 Skill。
自动加载：你不需要手动告诉 Agent"现在用 XX Skills”，Agent 会根据你的任务描述，自动判断需要哪个Skil，然后动态加载。

1.2 Skills 文件结构

1）基本结构

my-skill/
├── SKILL.md          # Required: instructions + metadata // YAML frontmatter + Markdown内容
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

详见：https://agentskills.io/what-are-skills

一个标准 Skill 由以下部分构成：

‌必需文件‌：SKILL.md
 ‌ - YAML 元数据‌：定义 name（调用标识）和 description（用途说明），用于 AI 自动识别与匹配。
‌  - Markdown 正文‌：详细描述执行流程、输入输出格式、注意事项与示例，指导 AI 精准执行。
‌可选子文件夹‌：
  - scripts/：存放 Python、Shell 等可执行脚本，实现自动化逻辑。
  - references/：提供模板、规范、案例等参考文档，提升输出准确性。
  - assets/：包含品牌素材、图标、样式表等静态资源，保障输出一致性。

结构即规范：Skill = 元数据 + 指令 + 资源，支持版本控制、跨平台共享。

2）SKILL.md详解
SKILL.md是核心文件，包含两部分：

第一部分：YAML Frontmatter

name: pdf-processor
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
allowed-tools: Read, Write, Bash

字段说明：

name：Skill名称（小写字母、数字、连字符，最多64字符）
description：功能描述和何时使用（最多1024字符）
allowed-tools：可选项，限制Claude能使用的工具

第二部分：Markdown内容

# PDF Processor

## Instructions
Step-by-step instructions for Claude...

## Examples
Concrete examples...

## Best Practices
Tips and recommendations...

3）完整示例
文件：~/.claude/skills/commit-helper/SKILL.md

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

进阶文件结构（技能变复杂时推荐）

当技能超过 500–800 行，或需要模板/脚本/参考资料时，推荐以下组织方式：

~/.claude/skills/react-component-review/
  ├── SKILL.md                  # 核心指令 + 元数据（建议控制在 400 行内）
  │
  ├── templates/                # 常用模板（Claude 按需读取）
  │   ├── functional.tsx.md
  │   └── class-component.md
  │
  ├── examples/                 # 优秀/反例（给 Claude 看标准）
  │   ├── good.md
  │   └── anti-pattern.md
  │
  ├── references/               # 规范、规则、禁用词表
  │   ├── hooks-rules.md
  │   └── naming-convention.md
  │
  └── scripts/                  # 可执行脚本（需开启 code execution）
      ├── validate-props.py
      └── check-cycle-deps.sh

在 SKILL.md 中引用方式示例：

Markdown需要给出标准函数组件时，参考 templates/functional.tsx.md 的结构。

如果违反 Hooks 规则，对照 references/hooks-rules.md 第 3–5 条说明。

如需校验 propTypes，可执行 scripts/validate-props.py "{代码片段}"。

Claude 看到路径引用后，会按需加载对应文件，而不是一次性全部塞入上下文，极大节省 token。

二、为什么是Skills

2.1 Skill 主要作用

Skill 的核心价值：标准化 + 复用 + 稳定输出，主要包含以下几点：
（1）成本问题：从"全量加载"到"按需加载"（节省 70-90% Token）
（2）孤岛问题：从"各自为政"到"统一标准"（跨工具复用）
（3）能力问题：从"泛泛而谈"到"领域专家"（专业 + 可执行）
（4）管理问题：从"散落各处"到"集中管理"（版本控制）

2.2 主要痛点与解决方案

1）专业知识鸿沟

# 问题：AI能写代码，却不了解团队的编码规范、审批流程和内部规则；
# 解决：将团队知识、经验和规范固化为Skill,AI即可掌握；

2）重复劳动低效

# 问题：每次都要反复说明需求格式和操作方法；
# 解决：一次配置、永久复用，AI按规范自动执行；

3）上下文冗余（Token浪费）

# 问题：将所有知识一次性加载到上下文，浪费Token;
# 解决：采用渐进式披露和按需加载，节省上下文资源；

4）能力难以复用

# 问题：不同项目/团队需要反复开发定制化agent;
# 解决：Skills 可跨项目、跨团队通用复用；

5）输出质量不稳定

# 问题：AI输出质量参差不齐，缺乏一致性；
# 解决：通过规范与固定流程，保证输出统一的高质量；

三、Skills 工作原理

3.1 自动发现机制

1）Claude如何发现Skills？

用户请求
    ↓
Claude扫描Skills目录
    ↓
读取所有SKILL.md的description
    ↓
匹配请求与description
    ↓
加载匹配的Skill
    ↓
按照Instructions执行

2）关键点
✅ Claude完全自主决策
✅ 用户无需手动调用
✅ 匹配基于description的语义

3.2 渐进式加载

Skill的设计很巧妙，它运行在一个沙盒环境里，这个环境允许大模型访问文件系统和执行 bash 命令(可以理解为一种电脑操作指令)。

在这个环境里，一个个Skill 就像一个个文件夹，Agent 就像一个熟悉电脑操作的人，通过命令行来读取文件、执行脚本，然后利用结果去完成你交代的任务。
在这里插入图片描述

1）三种技能内容类型，三种加载级别
为了平衡效果和效率，Skills 设计了一套聪明的三层分级的渐进式加载机制。
在这里插入图片描述

Level 1：元数据（始终加载）：Skill 的 YAML 前置信息提供了发现信息:Claude 会在启动时加载这些元数据并将其包含在系统提示中。这种轻量级方法意味着你可以安装许多技能而不会受到上下文限制;Claude 只知道每个技能的存在以及何时使用它们。

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

Level 2：指令（触发时加载）：SKILL.md 的主体包含程序性知识、工作流程、最佳实践和指导。只有用户的请求和 Skils 元数据里的描述相符时，Claude 才会用 bash 指令读取这份文档，把内容加载到上下文里。

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

Level 3：资源和代码（按需加载） ：Skills 还能打包一些更深入的资源，比如更详细的说明文档（FORMS.md）、可执行脚本（.py）或者参考资料（像 API 文档、数据库结构等）。Claude 只有在需要的时候，才会通过 bash 去读取或执行这些文件，而且脚本代码本身不会进入上下文。这样一来，Skills 就能捆绑大量信息，几乎不会增加额外的上下文成本。

pdf-skill/
├── SKILL.md          # 必需：main instructions
├── reference.md      # 可选：详细文档 API reference
├── scripts/          # 可选：辅助脚本
│   └── fill_form.py

2）Skills 的调用逻辑：从理解意图到稳定执行
那么，Agent 是如何智能地选择并执行一个 Skill 的呢？整个过程就像一位经验丰富的助理在处理工作：
在这里插入图片描述
详细执行过程：

意图匹配（找到对的人）：Agent 首先聆听你的需求，然后快速扫一眼自己手头所有 Skill 的“名片夹”（元数据），寻找最匹配的那一张。
读取手册（看懂怎么干）：找到合适的 Skills 后，Agent 会像模像样地翻开它的“操作手册”（SKILL.md），仔细研究详细的执行步骤和注意事项。
按需执行（动手开干）：根据手册的指引，Agent 开始工作。如果需要，它会随时从“工具箱”里拿出脚本或工具来完成具体操作。
反馈结果（事毕复命）：任务完成后，Agent 向你汇报最终结果，或者在遇到困难时，及时向你请教。

3）详细加载过程示例

Claude不会一次性加载所有文件：

第一次请求：
  加载 SKILL.md
      ↓
需要更多信息？
  是 → 加载 reference.md
      ↓
需要执行脚本？
  是 → 加载 scripts/helper.py
      ↓
需要模板？
  是 → 加载 templates/template.txt

好处：

✅ 节省Token
✅ 提高性能
✅ 只加载必要信息

四、Skiils 最佳实践

4.1 Good Skills vs Bad Skills

评判维度	Good Skills	Bad Skills
单一职责原则	每个Skill只做一件事，且把它做好。例如，可以分解为三个独立的Skill：query_data、 generate_chart、send_email。	一个Skill试图做太多事，比如 “既负责数据查询，又负责图表生成，还负责邮件发送”。
描述清晰度	描述清晰、具体，使用自然语言，明确说明输入、输出和核心功能。例如：“根据用户提供的城市名和日期范围，查询并返回该城市的天气数据。”	描述模糊，充满技术术语，智能体难以理解。例如：“一个用于数据处理的工具。”
参数设计	参数精简、命名语义化（如city_name、 date_range），并为每个参数提供清晰的描述和示例。明确使用Skill需要的参数如何获取，以及参数如何使用。	参数过多、命名不规范（如 arg1、p2），缺少详细的注释说明。
可组合性	设计时就考虑到了可组合性，其输出可以作为其他 Skill的输入，方便构建更复杂的任务流（Workflow），可以尝试通过单一职责完成原子 Skill的开发，并通过某项具体任务SOP Skill完成协调。	设计上是“一锤子买卖”，难以与其他Skill联动。

4.2 如何写好 Skills

1）原子性（Atomicity）：坚持单一职责，让每个 Skill 都像一块积木，小而美，专注于解决一个具体问题，便于日后的复用和组合。

2）给例子（Few-Shot Prompting）：这是最关键的一点，与其费尽口舌解释，不如直接给出几个清晰的输入输出示例。榜样的力量是无穷的，模型能通过具体例子，秒懂你想要的格式、风格和行为。

3）立规矩（Structured Instructions）：

定角色：给它一个明确的专家人设，比如“你现在是一个资深的市场分析师”。
拆步骤：把任务流程拆解成一步步的具体指令，引导它“思考”。
画红线：明确告诉它“不能做什么”，防止它天马行空地“幻觉”

4）造接口（Interface Design）：像设计软件 API 一样，明确定义 Skill 的输入参数和输出格式（比如固定输出 JSON 或 Markdown）。这让你的 Skill 可以被其他程序稳定调用和集成。

5）勤复盘（Iterative Refinement）：把 Skills 当作一个产品来迭代。在实际使用中留心那些不尽如人意的“Bad Case”，然后把它们变成新的规则或反例，补充到你的 Skills 定义里，让它持续进化，越来越聪明、越来越靠谱。

五、Skills vs 其它方案对比

5.1 Skills vs MCP（Model Context Protocol）

用 Anthropic 官方的说法：
　　MCP 解决"连接"问题：让 AI 能访问外部世界
　　Skill 解决"方法论"问题：教 AI 怎么做某类任务

我觉得，Skills 用于知识复用，MCP 用于能力扩展。

Skills（知识复用）	MCP（能力扩展）
1. 知识分享：经验、最佳实践、工作流程 2. 基于简单的 Markdown 文件，任何人都可以创建 3. 渐进式加载，Token 使用效率高 4. 无需服务器或后端设置 5. 适用于 Web / Desktop / CLI	1. 功能扩展：连接 API、数据库、外部工具 2. 需要编码能力和服务器端配置 3. 启动时加载全部工具定义 4. 对外部系统集成能力强 5. 更高的 Token 消耗与复杂度

5.2 Skills vs 传统 Prompt

按需加载 + 渐进式披露（只在需要时才把厚厚的 SOP 塞进上下文，极大节省 token）

对比项	普通 Prompt	Skills 机制
每次都要重新描述	是	否（只描述一次）
上下文长度占用	每次全量塞入	渐进式加载（只在触发时才读完整内容）
一致性	依赖每次 prompt 质量	高（固定 SOP + 模板）
复用性	手动复制粘贴	自动匹配/ slash 命令/项目共享
维护方式	改一次 prompt 就要重新发	修改 SKILL.md 文件，全局/项目生效

以 Anthropic 官方 Skills 为例：

PDF：包含 PDF 合并、拆分、文本提取等代码脚本，教会 Agent 如何处理 PDF 文件 - 提取文本，创建新的 PDF、合并或拆分文档。
Brand-guidelines：包含品牌设计规范、Logo 资源等，Agent 设计网站、海报时，可参考 Skill 内的设计资源，自动遵循企业设计规范。
Skill-Creator：把创建 Skill 的方法打包成元 Skill，让 AI 发起 Skill 创建流程，引导用户创建出符合需求的高水准 Skill。

但 Skills 的价值上限，远不止于此。

六、Skills 局限性与注意事项

待补充

七、总结与材料

7.1 最后总结

Agent Skills 不只是一个格式标准，它代表了 AI 工具行业从"野蛮生长"进入"工程化"的转折点。就像 npm 定义了前端生态，Docker 定义了容器生态，Agent Skills 可能定义 AI Agent 生态

Skill 的出现，为 AI 从“对话式助手”转变为“可信赖的执行者”搭建了关键的技术桥梁。它用结构化的方法把领域知识、操作流程和工具调用逻辑封装起来，解决了 Agent 规则失效、执行失控的混乱问题，让 AI 的能力输出变得可以控制、值得信赖且高效。

Skill 的核心价值在于：

精准实际痛点：通过巧妙的三级加载机制（元数据→说明文档→资源）平衡上下文效率与功能深度，在功能深度和上下文效率之间找到了一个绝佳的平衡点，既避免了宝贵 Token 的浪费，又确保了任务执行的精准性，实现了 Agent 上下文的动态加载能力。
生态赋能，降低门槛：无论是官方还是社区，都提供了丰富的资源（如 Claude 官方仓库、SkillsMP 市场等），让普通用户也能轻松站在巨人的肩膀上，快速复用各种成熟的能力。

虽然 Skill 不是万能的，但它在“确定性流程任务”上的优势无可替代。未来，随着 AI 模型能力的提升与 Skill 生态的进一步完善，我们有望看到更多跨领域、可组合的 Skill 出现——让 AI 从“样样懂一点”的通才，真正进化为“事事做得好”的专家协作伙伴。