Anthropic「Skills」是什么？——面向 AI 的“插件生态”（一）

相关文档：
Claude Code 构建 Agent Skills官方文档
Agent Skills 学习与案例库
行业化的 AI 模板库
https://github.com/anthropics/skills

---

---

说明：本文基于本地仓库 anthropics/skills 的 README.md 和 spec/agent-skills-spec.md，对其中所有关键概念、章节和代码进行系统性翻译与解读，力求不遗漏原文信息，并做适度扩展说明，方便中文读者理解。

Anthropic 的 Skills（技能）并不是“模型参数”或“传统 SDK”，而是一套专门为 AI 代理（Agents） 设计的可加载工作流与说明书：

• 从形式上看：一个 Skill 就是一个文件夹，里面有一个 SKILL.md 以及若干脚本、资源。
• 从作用上看：Skill 用来 教会 AI 怎么完成一个具体类别的任务，并且可以被动态加载、复用与组合。
• 从使用方式看：开发者或高级用户可以将这个仓库注册到 Claude Code / Claude.ai / API 中，作为“技能市场”，按需调用。

原仓库官方定义可以概括为：

Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks.

即：技能 = 可被 Claude 动态加载的指令 + 脚本 + 资源集合，用于提升在特定任务上的表现。

---

1 Skills 仓库结构与内容概览

1.1 Skills结构的简易解释

参考自：equipping-agents-for-the-real-world-with-agent-skills

1.1.1 Skills技能的构成

为智能体构建一个 skill 就像为新员工准备入职指南。与其为每个用例构建零散的、定制的智能体，不如通过捕捉和分享程序化知识，让任何人都能用可组合的能力来专门化他们的智能体。在本文中，我们将解释什么是 Skills，展示它们的工作原理，并分享构建你自己的技能的最佳实践。

技能是包含一个 SKILL.md 文件的目录，里面有组织的指令、脚本和资源，赋予智能体额外能力。

让我们通过一个真实例子来了解 Skills：这是支持 Claude 最近推出的文档编辑能力 的技能之一。Claude 已经对理解 PDF 有很深的认识，但在直接操作 PDF（例如填写表单）方面能力有限。这个 PDF 技能 让我们赋予 Claude 这些新能力。

最简单的技能是一个包含 SKILL.md 文件的目录。该文件必须以 YAML Frontmatter 开头，包含一些必需的元数据：name 和 description。启动时，智能体会将所有已安装技能的 name 和 description 预加载到系统提示中。

这些元数据是渐进式披露的第一层：它提供足够的信息让 Claude 知道何时应该使用每个技能，而无需全部加载到上下文中。
该文件的正文是第二层细节。如果 Claude 认为该技能与当前任务相关，它将通过读取完整的 SKILL.md 文件来加载该技能。

随着技能的复杂度增加，可能会包含过多上下文，无法全部放入单个 SKILL.md，或者包含仅在特定场景下相关的上下文。这时，技能可以在目录中捆绑额外的文件，并在 SKILL.md 中通过名称引用它们。这些额外的链接文件是第三层（及更深层次）的细节，Claude 可以根据需要选择性地导航和发现。

在下面的 PDF 技能示例中，SKILL.md 引用了两个额外文件（reference.md 和 forms.md），技能作者选择将它们与核心的 SKILL.md 一起打包。通过将表单填写说明移到单独的文件 forms.md 中，技能作者可以保持核心技能文件的精简，并相信 Claude 只在填写表单时才会读取 forms.md。

你可以通过额外文件为技能加入更多上下文，然后由 Claude 根据系统提示触发这些内容。

渐进式披露是 Agent Skills 灵活且可扩展的核心设计原则。就像一本结构良好的手册，从目录开始，然后是具体章节，最后是详细附录，技能让 Claude 只在需要时加载信息：

具备文件系统和代码执行工具的智能体，无需在处理特定任务时将整个技能加载到上下文窗口中。这意味着技能中可打包的上下文量实际上是无限的。

1.1.2 技能与上下文窗口

下图展示了当技能被用户消息触发时，上下文窗口的变化。

技能通过系统提示在上下文窗口中被触发。

操作序列如下：

1. 初始时，上下文窗口包含核心系统提示、所有已安装技能的元数据，以及用户的初始消息；
2. Claude 通过调用 Bash 工具读取 pdf/SKILL.md 内容，触发 PDF 技能；
3. Claude 选择读取与技能捆绑的 forms.md 文件；
4. 最后，Claude 在加载了 PDF 技能的相关指令后，继续执行用户的任务。

1.1.3 技能与代码执行

技能还可以包含 Claude 可按需执行的代码工具。

大型语言模型在很多任务上表现优异，但某些操作更适合传统代码执行。例如，通过生成 token 来排序列表比直接运行排序算法代价高得多。除了效率问题，许多应用需要代码才能提供的确定性可靠性。

在我们的示例中，PDF 技能包含一个预写的 Python 脚本，用于读取 PDF 并提取所有表单字段。Claude 可以在不将脚本或 PDF 加载到上下文中的情况下运行该脚本。由于代码是确定性的，该工作流既一致又可重复。

技能可以根据任务性质，包含 Claude 可执行的代码工具。

1.1.4 开发与评估技能

以下是一些有助于开始编写和测试技能的指导原则：

• 从评估开始： 通过在代表性任务上运行智能体，识别其能力缺口，观察其在哪些地方表现不佳或需要额外上下文。然后逐步构建技能以解决这些不足。
• 结构化以便扩展： 当 SKILL.md 文件变得庞大时，将内容拆分到多个文件中并进行引用。如果某些上下文是互斥的或很少一起使用，分开路径可以减少令牌使用量。代码既可以作为可执行工具，也可以作为文档，应明确 Claude 是直接运行脚本还是将其作为参考读入上下文。
• 从 Claude 视角思考： 监控 Claude 在实际场景中如何使用你的技能，并根据观察进行迭代：注意意外的路径或对某些上下文的过度依赖。特别关注技能的 name 和 description，Claude 会用它们来决定是否针对当前任务触发技能。
• 与 Claude 一起迭代： 在与 Claude 共同完成任务时，让 Claude 将成功的方法和常见错误捕获到可重用的上下文和代码中。如果它在使用技能完成任务时偏离轨道，询问它自我反思哪里出错。此过程将帮助你发现 Claude 实际需要的上下文，而不是试图提前预判。

1.1.5 使用技能时的安全考虑

技能通过指令和代码为 Claude 提供新能力。虽然这增强了技能的力量，但也意味着恶意技能可能引入使用环境中的漏洞，或指示 Claude 泄露数据和执行非预期操作。

我们建议仅从可信来源安装技能。安装来自不太可信来源的技能时，务必先彻底审计。首先阅读技能中所有文件的内容，了解其功能，特别关注代码依赖和捆绑的资源（如图片或脚本）。同样，注意技能中是否有指示 Claude 连接到潜在不可信外部网络的指令或代码。

1.2 Anthropic Skills 仓的结构

来看一下https://github.com/anthropics/skills 仓的结构

根据 README.md，这个仓库的顶层结构大致如下（简化说明）：

• ./skills：大量示例技能目录，涵盖：
  • 创意与设计（艺术、画图、UI）
  • 开发与技术（测试、MCP 工具生成）
  • 企业与沟通（品牌、内部沟通）
  • 文档处理（docx、pdf、pptx、xlsx）
• ./spec：Agent Skills 规范，说明 Skill 的文件结构和 SKILL.md 的格式。
• ./template：一个模板 Skill，用来作为创建新 Skill 的起点。
• .claude-plugin/：与 Claude Code 插件系统集成相关的元数据。
• README.md：你目前看到的总说明文件。

原文还特别强调：

Many skills in this repo are open source (Apache 2.0)。
文档创建与编辑技能（docx、pdf、pptx、xlsx）是 source-available 而非开源，但作为复杂生产级技能的参考被开放出来。

这意味着：

• 绝大部分示例技能可以自由参考和复用；
• 文档类技能则代表了 Anthropic 自己在生产环境中给 Claude 用的“官方技能实现”，非常适合作为你设计企业级文档系统的参考。

---

2、Skills 的核心概念：Skill 与 SKILL.md

2.1 Skill 的正式定义（来自 Agent Skills Spec）

在 spec/agent-skills-spec.md 中，对 Skill 的正式定义是：

A skill is a folder of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.

翻译并拆解：

• “folder of instructions, scripts, and resources”：Skill 是一个目录，里面放：
  • 说明文档（指示 AI 怎么做）
  • 脚本（如 Python、JS，供 AI 生成或调用）
  • 资源（如模板、示例、图片等）
• “agents can discover and load dynamically”：Agent（如 Claude）可以根据任务需要：
  • 动态发现这些 Skill；
  • 按需加载与执行其中的流程或脚本；
• “perform better at specific tasks”：Skill 是任务特化的：例如只负责“PDF 处理”或“PPT 生成”，强调在某类任务上的高质量与可重复性。

2.2 从“Skill Sets” 看技能类别与场景

README.md 中把仓库中的技能粗略分为几类，并使用了“Skill Sets”的说法：

• ./skills：各种领域的技能：
  • Creative & Design（创意与设计）
  • Development & Technical（开发与技术）
  • Enterprise & Communication（企业与沟通）
  • Document Skills（文档技能）
• ./spec：Agent Skills 规范；
• ./template：技能模板。

结合前面的 list_files，我们可以列出几个代表性 Skill 目录（部分）：

目录名	主要领域	典型用途简述
pdf	文档处理	PDF 拆分、文本/表格/图片提取、表单处理等
docx	文档处理	Word 创建、编辑、修订、批注、结构化读取
pptx	文档 & 演示处理	PPT 创建/编辑、模板套用、文本批量替换等
xlsx	数据 & 表格处理	Excel 读取、写入、公式校验、格式规范等
canvas-design	视觉设计	画海报、插画、静态视觉稿（输出 PNG/PDF）
algorithmic-art	算法艺术	使用 p5.js 等生成算法图形
frontend-design	前端页面设计	生成页面布局、组件结构和 CSS 风格
web-artifacts-builder	复杂 Web 产物	使用 React/Tailwind/shadcn 搭建复杂 Web 组件
doc-coauthoring	文档协作写作	引导式写技术文档/提案/说明书
theme-factory	主题与品牌	统一主题配色与字体，生成主题示例（有 PDF 展示）

图片提示：
仓库中 theme-factory/theme-showcase.pdf 是一个 PDF 示例，用来展示不同主题样式的效果，可视作“图片资源集”的 PDF 版展示。[来源：skills/theme-factory/theme-showcase.pdf]

---

3 Skills 的使用：从 Claude Code 到 Claude.ai 再到 API

README.md 的后半部分详细说明了在不同产品中如何使用这些技能。可以概括为三个场景：Claude Code、Claude.ai、Claude API。

3.1 在 Claude Code 中使用 Skills

官方建议可以把这个仓库当作一个“插件市场源”来注册：

/plugin marketplace add anthropics/skills

代码解读：

• /plugin marketplace add：Claude Code 中的命令，用于添加一个插件市场源；
• anthropics/skills：GitHub 仓库标识，即当前这个 Skills 仓库。

注意事项：

• 该命令在 Claude Code 环境中执行，而不是在系统 shell 中执行；
• 添加后，你可以在 Claude Code 的 UI 中浏览和安装其中的技能集合（例如 “document-skills”、“example-skills”）。

之后有两种安装方式：

1. 通过 UI 操作：

   • 在 Claude Code 里选择「Browse and install plugins」；
   • 选择 anthropic-agent-skills；
   • 再选择安装 document-skills 或 example-skills；
   • 点击 Install now。

2. 通过命令直接安装：

   /plugin install document-skills@anthropic-agent-skills
   /plugin install example-skills@anthropic-agent-skills
   

   代码解读：

   • /plugin install：安装插件；
   • document-skills@anthropic-agent-skills：
     • anthropic-agent-skills：插件集合名称；
     • document-skills：该集合中的一个具体插件（下挂多个与文档相关的 Skill）。

   注意事项：

   • 名称需要精确匹配；
   • 安装后，只需在对话中说“使用 PDF skill ……”，就能让 Claude 自动调用对应的 Skill。

README 给了一个典型用例：

“Use the PDF skill to extract the form fields from path/to/some-file.pdf”

翻译为普通话对话就是：

• 你在 Claude Code 里对模型说：
  • “请使用 PDF skill，从 path/to/some-file.pdf 里抽取所有表单字段。”
• Agent 会：
  • 检查已安装的 document-skills；
  • 激活 pdf 这个 Skill；
  • 按 skills/pdf/SKILL.md 中的流程，使用合适的 Python 工具（如 pdfplumber）完成任务。

---

3.2 在 Claude.ai 中使用 Skills

README 指出：

These example skills are all already available to paid plans in Claude.ai.

即：对于 Claude.ai 的付费用户，这些示例 Skills 已经可用，无需你手动配置仓库。

你只需按照官方文档：

• 参考链接：Using skills in Claude
• 在 Claude.ai 的界面中上传或启用这些 Skills。

在实际对话中，使用方式类似：

• “用 docx skill 帮我生成一份项目计划书草稿。”
• “用 xlsx skill 分析这份销售数据表，并输出关键指标。”

---

3.3 通过 Claude API 使用 Skills

README 还提到可以通过 API 使用预置 Skill 或自定义 Skill：

You can use Anthropic’s pre-built skills, and upload custom skills, via the Claude API. See the Skills API Quickstart.

对应官方文档链接是：

• Skills API Quickstart: https://docs.claude.com/en/api/skills-guide#creating-a-skill

在 API 级别，本质是：

1. 把你的 my-skill/ 目录（含 SKILL.md）上传到 Anthropic 的 Skill 系统；
2. 在调用模型时，通过接口参数告知使用某些 Skill；
3. Agent 在推理过程中按这些 Skill 的说明来规划、调用工具、执行脚本。

3.4 在其他 IDE 插件（CodeBuddy, Trae, Cursor 等）中使用

除了 Anthropic 官方支持的渠道，许多第三方工具，尤其是深度集成的 IDE 插件，也提供了使用 Skills 的方式。这些工具大致可以分为两类：

1. 深度集成环境（如 CodeBuddy）

这类工具通常内置了对 Skills 理念的支持，提供了类似 Claude Code 的无缝体验。以 CodeBuddy 为例，其对 Skills 的支持非常完整：

• 自动加载与执行：当你在 CodeBuddy 中提到要使用某个 Skill 时（例如 pptx），它能够自动加载对应的 SKILL.md 文件，并将其中的工作流、脚本路径、工具列表等信息注入到当前的对话上下文中。
• 内置工具调用：如果 Skill 需要执行本地脚本（如 pptx skill 中用于操作 OOXML 的 Python 脚本），CodeBuddy 提供了让 AI 安全执行这些脚本的能力。AI 会生成一个执行指令，经用户确认后，在 CodeBuddy 的环境中运行，并将结果返回给 AI。
• 闭环工作流：从“激活 Skill” -> “AI 按 SKILL.md 规划任务” -> “调用工具/脚本” -> “返回结果”，整个过程是闭环的，用户体验非常流畅。

在这种环境下，使用 Skill 的方式与在 Claude Code 中几乎没有差别，核心在于工具本身是否实现了 Skill 的发现、加载和执行机制。

2. 通用“自带 Key”环境（如 Trae, Cursor, Qoder 等）

对于更多通用的、允许用户“自带 API Key”的 AI 编码助手（如 Trae, Cursor, Qoder 等），它们可能没有专门为 Skills 设计的集成功能。但在这些工具中，你仍然可以手动模拟 Skill 的使用过程：

1. 手动“安装” Skill：将 skills/SKILL_NAME/SKILL.md 的全部内容，以及任何相关的脚本文件（如 scripts/main.py），手动添加到对话的上下文中。你可以直接复制粘贴 SKILL.md 的内容，或者使用插件的“附加文件”功能。这一步相当于手动“教会” AI 这个 Skill 的工作流程。

2. 引导 AI“执行” Skill：

   • 对于纯 Prompt 类 Skill：AI 读取 SKILL.md 后，就可以遵循其中的指导和示例来回答你的问题。
   • 对于需要代码生成的 Skill：AI 会根据 SKILL.md 中的规范生成代码，你需要手动复制并应用到你的项目中。
   • 对于需要执行脚本的 Skill（如 pptx）：这是最复杂的情况。AI 在读取 SKILL.md 后，会知道需要调用某个脚本。但由于这些通用工具通常不具备让 AI 直接执行本地代码的能力，AI 会“请求”你来执行。它会生成需要运行的命令（例如 python skills/pptx/scripts/run.py --action "create_slide" ...），你需要自己复制这个命令到终端里执行，然后将终端的输出结果再复制回对话框，告诉 AI 执行结果。

总结：在 Trae、Cursor 这类工具中，使用 Skills 更像是一种**“人机协作”的模式**。SKILL.md 成为你和 AI 共同遵循的“操作手册”，AI 负责规划和生成指令，而你负责执行其中需要外部环境支持的步骤。虽然不如深度集成环境来得自动化，但这极大地扩展了 Skills 在各种开发环境中的适用性。

---

4 创建你自己的 Skill：流程与对比

README.md 对“如何创建一个基础 Skill”给了一个核心样例（前面已经展示了代码），这里我们将整个过程总结为步骤，并做一点对比说明。

4.1 创建基础 Skill 的步骤

1. 新建 Skill 目录

   my-skill/
     - SKILL.md
   

2. 编辑 SKILL.md 的 YAML 部分

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

3. 填写 Markdown 正文

   • # My Skill Name：整体标题；
   • ## Examples：写 2–3 个对话中的使用示例；
   • ## Guidelines：写清楚该 Skill 的使用原则（如“避免一次修改过多文件”、“遇到错误优先回滚”等）。

4. 按需添加脚本与资源

   • 若 Skill 需要执行 Python 脚本，可以在该目录下加 scripts/。
   • 若需要模板文件（如 Word 模板、PPT 模板），可建立 templates/。

5. 在 Claude 环境中加载或上传

   • Claude Code：通过 /plugin 命令或 UI。（见上文）
   • Claude.ai：通过网页版的 Skill 配置入口。
   • API：通过 Skills API 上传。

4.2 Skill 与其它概念的对比（表格）

为了更清晰地理解 Skill 与传统组件（如插件、工具、普通 prompt）的区别，可以用表格对比：

概念	粒度与形式	谁来执行？	典型内容
Prompt	单段文本提示	纯大模型（LLM）	指令、问题、上下文描述
Tool	一个具体 API / 命令行 / 函数	外部系统或代码	HTTP 请求、DB 查询、脚本调用
Plugin	一组工具与集成逻辑	应用/平台 + LLM	多个 API、配置与 UI 绑定
Skill	一整个“任务工作流 + 说明书 + 资源”的目录	LLM 主导 + 工具辅助	SKILL.md + scripts + 模板 + 规则

从表中可以看出：

• Skill 更像是**“让 LLM 成为高级工程师/助理的 SOP 手册 + 工具箱”**；
• 它比单一 Tool 粒度更大，涵盖“怎么规划任务、如何分步调用工具、如何处理错误”等。

---

4.3 Agent Skills 规范的关键要点（进一步细节）

spec/agent-skills-spec.md 是对 Skills 的正式规范文件，前面我们已经引用核心内容，这里补充它的结构与版本信息。

4.3.1 规范内容提要

1. Skill 定义：前文已述。

2. Skill Folder Layout（技能目录结构）：

   my-skill/
     - SKILL.md
   

   说明：即使 Skill 非常复杂，入口仍然是 SKILL.md。

3. The SKILL.md file：

   • 必须包含 YAML frontmatter；
   • 前面详细介绍了必选与可选字段。

4. Additional Information：

   • 若想要一个最小示例，可以参考仓库中的 template-skill。

5. Version History（版本历史）：

   规范当前版本信息为：

   • 1.0 (2025-10-16) Public Launch —— 即 2025-10-16 公开发布 1.0 版规范。

4.3.2 规范与实践结合的几点结论（并注明出处）

1. Skill = 目录 + SKILL.md + 资源

   • 出处：Agent Skills Spec 开头段落
   • 实践意义：你在设计任何 Skill 时，都可以先从一个最小目录 + SKILL.md 开始，逐步添加脚本与资源。

2. YAML Frontmatter 的 name 与目录名需要一致

   • 出处：规范中对 name 字段的要求
   • 实践意义：保证 Skill 的“逻辑名称”和“物理目录”一致，有利于自动发现和维护。

3. Markdown 正文自由度高，但结构化越好

   • 出处：Markdown Body has no restrictions
   • 实践意义：建议你把 SKILL 文档写成一份“人类可读、Agent 可遵循”的操作手册，而不是仅仅给几行说明。

4. 1.0 规范已经稳定，可直接用作企业内部标准

   • 出处：Version History 标记为 Public Launch
   • 实践意义：如果你要在公司内部推广自身 Skill 体系，可以直接参考该规范制定组织标准。

---

5 小结：anthropics/skills 能帮你做什么？适合谁用？

综合 README.md 与 agent-skills-spec.md 的全部信息，我们可以对这个仓库做一个较为客观的总结：

1. 它是什么？

   • 一个面向 AI Agent 的“技能集合”仓库；
   • 每个 Skill 是一个目录，内含 SKILL.md、脚本与资源；
   • Skill 是“教 AI 做事”的模块化单元。

2. 它解决什么问题？

   • 让复杂任务（如 PDF/PPT/Docx/Xlsx 处理、Web 设计、算法艺术等）被抽象成可复用的工作流；
   • 让不同项目中的 Agent 能共享并复用这些工作流；
   • 提供了一套可扩展的“企业级 AI 能力装配”方式。

3. 适合谁用？

   • 想给 Claude“装插件”的开发者与团队；
   • 希望沉淀内部流程、标准与规范为“AI 可用指令集”的组织；
   • 想搭建自己的“AI 开发者平台 / 文档工作台 / 设计工作台”的产品经理与架构师。

4. 如何开始？

   • 阅读本仓库的 README.md 和 spec/agent-skills-spec.md（本文已覆盖关键内容）；
   • 在 Claude Code 中添加插件市场 anthropics/skills，试用现成的技能集合；
   • 从 template-skill 复制一份，按需修改 SKILL.md，编写自己的 Skill；
   • 将 Skill 通过 Claude Code / Claude.ai / API 引入你的工作流与产品。

关键结论出处：

• Skill 概念与结构：spec/agent-skills-spec.md
• 仓库整体说明与使用方式：README.md
• 文档技能与示例技能的具体内容：skills/ 目录下各个 SKILL.md（如 docx、pdf 等）