Claude Agent Skills 技术笔记

参考资料：
– Anthropic 官方 Agent Skills 概览与指南
– Agent Skills 概览：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
– Skills API 使用：https://platform.claude.com/docs/en/build-with-claude/skills-guide
– Claude Code Skills 文档：https://code.claude.com/docs/en/skills
– Agent Skills 标准规范：https://agentskills.io/specification
– Anthropic Skills 示例仓库：https://github.com/anthropics/skills

1. 什么是 Skill

1.1 Skill 的本质与定位

从官方定义出发，Agent Skill 可以理解为：

一个封装了「任务说明 + 元数据 + 可选资源/脚本」的模块，用来扩展 Claude 在某一类任务上的表现，并在需要时自动被调用。

换成开发者语言：

  • Skill ≈「可被 LLM 自动调用的、声明式的函数模块」
  • 它不一定直接连接外部 API（那是 Tool / MCP 的职责），而是：
    • 把领域知识、工作流步骤、输入输出约定固化下来
    • 可选地，编排底层 Tools/MCP 调用
    • 让 Claude 在遇到相应任务时，不是「从零思考」，而是「按你设计好的流程执行」

Skill 的核心特征：

  • 模块化：一个 Skill 只负责一类任务（如代码审查、报表分析、PDF 处理）
  • 声明式：主要由文档式说明（Markdown）+ 元数据（YAML frontmatter）组成
  • 可组合：可以调用 Tools 或 MCP server，将「工具」组织成「业务工作流」
  • 跨平台标准：遵循 Agent Skills 开放标准，理论上可以在多种 Agent 平台之间迁移[agentskills]

1.2 Skill 的内部结构概览

官方与 Agent Skills 规范中，对 Skill 目录结构有相对统一的约定：

my-skill/
├── SKILL.md # 必须：Skill 主体定义（frontmatter + 指令）
├── scripts/ # 可选：可执行脚本（Python / Bash 等）
├── references/ # 可选：参考资料（如 API 文档、Schema）
├── assets/ # 可选：图片等静态资源
└── templates/ # 可选：输出模板 / Prompt 片段

其中最关键的是 SKILL.md：

  • 顶部是 YAML frontmatter：
    • 最少包含：
      • name: 技能名称
      • description: 描述 + 何时使用
    • Claude / Agent 会基于这些字段来：
      • 决定是否加载 & 何时激活该 Skill
      • 展示给用户（在 UI 中列出可用技能）
  • 后面是 Markdown 指令正文：
    • 以「写给 Claude 自己看的 SOP」形式，指导它如何执行任务

规范要求：SKILL.md 必须包含 YAML frontmatter + Markdown 正文；

正文无格式限制，但推荐采用结构化章节以提升效果。

1.3 Skill 与 Agent Skills 标准

Anthropic 推出的 Skills 遵循 Agent Skills 开放标准（https://agentskills.io）：

  • 已标准化的部分：
    • SKILL.md 的文件形态
    • YAML frontmatter 的基本字段和语义（至少 name + description）
    • 「脚本/资源/模板」等目录的推荐组织方式
  • 可扩展的部分：
    • frontmatter 可以增加任意字段，Agent 只解析自己关心的部分，其余忽略
    • 指令正文可以自由组织

对程序员的意义：

  • Skill 文件本质上是 可移植的配置 + 文档 + 轻量代码包
  • 你可以：
    • 在本地 .claude/skills/ / ~/.claude/skills/ 中维护
    • 在 Git 仓库中管理、协作
    • 通过 API 上传，变成 Workspace 级的可复用资产[^skills-guide]

2. Skill 和 Tools 的区别

2.1 总体对比表

这里的 Tools 主要指：Claude API 中的工具（包含 MCP 工具）、代码执行工具等。

维度 Skill Tool（含 MCP 工具）
核心职责 封装工作流、领域知识、任务说明 暴露一个具体能力 / API（如 HTTP 调用、DB 查询）
形式 SKILL.md + 可选脚本/资源 JSON/Schema 定义的工具接口 + 服务端实现
与 Claude 的接口 通过 技能容器 或 Claude Code 自动加载 通过 tools / MCP 协议 / code-execution
擅长 复杂流程、业务 SOP、跨工具编排 单一操作、外部系统集成、需要强可靠性的调用
依赖环境 可使用代码执行环境访问本地文件、脚本等 取决于工具实现：HTTP 服务、MCP server、本地命令等
对用户暴露程度 可以在 UI 中以“技能名称”方式呈现 通常由 Agent 选择是否调用，对终端用户不可见
编写主体 业务/产品/领域专家 + 工程师 工程师 / 系统集成人员
典型内容 分步说明、输入输出约定、示例、边界情况处理 参数 schema、返回格式、错误码、调用限制
安全风险 主要是错误指令、误用；可通过审阅 Markdown 降低 可能直接访问敏感数据 / 产生副作用，需要更严密权限控制
测试方式 通过“让 Claude 按 Skill 执行多轮任务”进行集成测试 单元测试 + 集成测试 + 端到端测试

简化理解：

  • Tool = API / 原子能力
  • Skill = 使用这些 API 的业务 Playbook（可自动执行）

2.2 能力分层：指令 vs 工具 vs 资源

官方文档将 Skill 内部内容分为三类：

  • Instructions（指令）
    • 就是 SKILL.md 中的 Markdown
    • 告诉 Claude “你是谁、你要做什么、怎么做”
  • Code（代码 / 脚本）
    • 放在 scripts/ 中的 Python、Bash 等脚本
    • 在 code-exec 环境中由 Claude 调用
  • Resources（资源）
    • 各类参考文档、Schema、模板、示例等
    • Claude 按需加载，避免一次性占满上下文

相比之下，Tool（尤其是 MCP 工具）是：

  • 提供“可调用的函数接口”（如 get_user(id)）
  • Skill 则会写成：
    • “当需要获取用户信息时，调用 get_user 工具，并在失败时重试 1 次；在汇总时忽略 404 错误”等

2.3 与 MCP 的关系

Anthropic 官方建议：先接好 MCP，再用 Skills 把 MCP 能力“封装成场景化技能”。

  • MCP server：
    • 把外部系统（SaaS、自研服务、数据库等）暴露成工具
    • 提供“原始能力”
  • Skill：
    • 站在业务视角，定义“如何在某个任务中正确使用 MCP 工具”
    • 例如 Sentry 官方示例的 sentry-code-review Skill：
      • 使用 Sentry MCP server 提供的错误数据
      • 自动分析 PR 与错误关联，并提出修复建议

因此，从架构角度看：

  • Tools/MCP = 能力层
  • Skills = 知识与流程层
  • Claude = 推理与执行层

3. 如何书写 Skill

这一节重点从工程视角讲「怎么写一个高质量的 SKILL」。

3.1 目录结构与放置位置

典型的本地 Skill 目录（以 Claude Code 为例）：[^code-skills]

.claude/
└── skills/
├── explain-code/
│ └── SKILL.md
├── pdf-processing/
│ ├── SKILL.md
│ ├── scripts/
│ │ └── extract_tables.py
│ └── references/
│ └── table-format-spec.md
└── …

常见放置路径：

  • 项目级 Skill（跟随仓库）：
    • <repo>/.claude/skills/<skill-name>/SKILL.md
  • 个人全局 Skill：
    • ~/.claude/skills/<skill-name>/SKILL.md
  • 其余 Agent 工具（如 OpenCode 等）也会兼容 .claude/skills & 自身的 .opencode/skills 目录。[^opencode]

目录名 & name 字段通常推荐使用 kebab-case 英文，如 code-review, pdf-processing。

3.2 SKILL.md 的 YAML frontmatter

根据 Agent Skills 规范和 GitHub 示例，最小 frontmatter 一般包含：[^skill-creator]

—
name: explain-code
description: >
Explain code snippets, functions, and files in clear, concise language.
Use when the user asks how some code works or requests a code walkthrough.
—

关键要点：

  • name
    • 作为技能的唯一标识
    • 一般用短小、动词短语式名字（如 review-pr, analyze-metrics）
  • description
    • 最重要字段，官方特别强调：
      • Claude 会用它来判断“什么时候用这个 Skill”[^skill-creator]
    • 写作建议：
      • 第一行：简短描述 Skill 能力
      • 后续：用自然语言描述「触发条件」和「适用场景」
        • 如 “Use when the user mentions PDFs, forms, or document extraction”

除了上述最小字段，Claude Code 文档中还提到可以在 frontmatter 中扩展一些控制项（具体字段因实现而异），例如：

  • 调用方式相关字段（示例概念）：
    • invoke: user | claude | both：是否允许用户显式调用 / 允许 Claude 自动调用
    • subagent: true/false：是否在子 agent 中运行（复杂任务）
  • 运行环境相关字段：
    • 是否需要长时间运行、是否偏向本地命令等
  • 标签/分类：
    • 方便 UI 或其他工具展示

未知字段一般会被解析器忽略，因此你可以为自己工具链增加额外元数据（如 owner, tags, version 等），只要不依赖 Claude 解析即可。

写 frontmatter 的实战建议

  • 把 description 当成「Skill 的型变模式匹配规则」来写：
    • 不仅写能力，还要写「何时用 / 何时不用」
  • 尽量使用用户侧语言描述场景，而不是实现细节：
    • ✅ “Use when the user asks to summarize long PDF documents”
    • ❌ “Uses pdfminer to extract text and then run a summarization model”

3.3 Markdown 正文：结构化指令

Agent Skills 规范建议：正文没有格式限制，但推荐分块，以便 Claude 更好理解。[^agentskills-spec]

一个典型的 SKILL.md 正文结构示例：

—
name: pdf-processing
description: >
Extract text and tables from PDF files, fill forms, and merge documents.
Use when working with PDF files or when the user mentions PDFs, forms,
or document extraction.
—

# Overview

This skill processes PDF files from the local file system.

# Capabilities

– Extract plain text
– Extract tables as CSV/Markdown
– Merge multiple PDF files
– Fill PDF form fields

# Inputs

– One or more PDF file paths
– Optional extraction options:
– `extract_tables`: boolean
– `pages`: list of page ranges

# Outputs

– For text extraction: a Markdown summary and optional raw text file
– For tables: Markdown tables and optional CSV files

# Workflow

1. Confirm the list of PDF files and their locations.
2. For each file:
– Verify it exists and is a valid PDF.
– If `extract_tables` is true, run the table extraction script.
– Otherwise, extract plain text.
3. Summarize the extracted content based on the user’s request.

# Edge Cases

– If a file is missing, report it and continue with the rest.
– If extraction fails, log the error and move on to the next file.

实践中非常推荐包含这些段落（标题可自定义）：

  • Overview / Purpose：一句话说明 Skill 干嘛
  • Capabilities：列出能力范围（Claude 会用来推理是否适用）
  • Inputs / Outputs：用自然语言描述输入输出形态
  • Workflow / Steps：分步过程（Claude 非常擅长按步骤执行）
  • Edge Cases / Limitations：显式说明不要做什么、如何处理异常
  • Examples：示例输入 / 输出，帮助 Claude 内化期望格式

3.4 资源文件与脚本的组织

根据官方示例仓库，Skill 可以携带多类资源：

pdf-processing/
├── SKILL.md
├── scripts/
│ └── extract_tables.py
├── references/
│ └── table-format-spec.md
└── templates/
└── summary.md

典型写法是在 SKILL.md 中显式引用这些文件，让 Claude 知道它们存在并如何使用：

# Scripts

Use `scripts/extract_tables.py` to extract tables as CSV files.
Call it with:

“`bash
python scripts/extract_tables.py –input “<pdf_path>” –output “<csv_path>”

References

See references/table-format-spec.md for the required output schema.

核心点：

– Skill 并不会自动“读完所有文件”— Claude 只会在你提示后按需读取：
– 你必须在 SKILL.md 中说明「什么时候需要读取哪个文件」
– 这实现了官方所说的 **progressive disclosure**：
– 避免一次性把所有文档塞进上下文
– 只在任务需要时才加载对应参考资料

3.5 基于 MCP / Tools 的 Skill 设计

如果你已经有一套 MCP server / 工具接口，Skill 编写可以只做一件事：

> 把“如何正确调用这些工具完成业务任务”写成清晰的步骤。

示例片段（概念化）：

“`markdown
# Workflow

1. Use the `sentry.search_issues` MCP tool to find errors related to the PR.
2. For each error:
– Fetch stack traces and related events.
– Identify the most likely root cause in the changed files.
3. Propose code changes that would fix the issues.
4. When unsure, ask clarifying questions instead of guessing.

Skill 不需要关心 MCP 的网络细节，只强调：

  • 调用哪些工具
  • 输入参数应该来自哪里（例如“从用户消息中的 repo 名读取”）
  • 如何汇总和呈现结果

3.6 编写流程与质量控制

可以把写 Skill 当成写「正式的、可执行的 SOP 文档」，建议流程：

  1. 确定单一清晰目标
    • 不要让一个 Skill 做太多事（例如“既做代码审查又做部署”）
  2. 设计前置条件和触发条件
    • 写在 description 和 Overview 中
  3. 用步骤分解任务
    • 让 Claude 能在每一步检查进度和中间结果
  4. 刻意写边界与反模式
    • 告诉 Claude「遇到 X 就停下并询问用户」
  5. 做回归与迭代
    • 官方文档强调：Skill 是“living documents”，需要根据使用反馈持续改进

4. 如何使用 Skill

这一节从「用户/开发者」视角，看 Skill 在不同场景下如何被调用。

4.1 在 Claude Code / IDE 中使用

Claude Code 文档说明：Skills 可被视为「增强版自定义命令」，与旧的 .claude/commands/*.md 兼容：

  • .claude/commands/review.md 和 .claude/skills/review/SKILL.md 都可以提供 /review 命令
  • Skills 额外支持：
    • 有独立目录，可以挂载脚本/资源
    • 使用 frontmatter 控制由谁调用（用户 / Claude / 二者皆可）
    • 基于描述自动加载

典型使用方式：

  1. 在项目中创建 .claude/skills/my-skill/SKILL.md
  2. 重启 / 打开 Claude Code（VS Code 扩展）
  3. 直接在聊天输入：
    • “/my-skill 给我审一下当前 PR”
    • 或普通自然语言：“帮我用代码审查技能检查这个 diff”
  4. Claude 会：
    • 解析当前环境（Git 仓库、打开的文件等）
    • 根据 description 判断是否需要加载该 Skill
    • 按 SKILL.md 中的步骤执行

4.1.1 使用流程的示意 Flowchart

4.2 在 Claude API 中使用

Anthropic 提供了 Skills 的 API 支持，可以将自定义 Skill 上传到 Workspace，并在调用 messages.create 时通过 container / code-execution 集成。

4.2.1 上传 Skill

官方 Python SDK 示例（简化版）：

import anthropic
from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# 使用目录上传一个 Skill
skill = client.beta.skills.create(
display_title=”Financial Analysis”,
files=files_from_dir(“/path/to/financial_analysis_skill”),
betas=[“skills-2025-10-02”],
)

print(skill.id, skill.version)

要点：

  • files 可以是：
    • files_from_dir(path)（推荐）
    • 或手动传入 zip / 文件列表
  • display_title 是在 UI / 控制台中展示的友好名称
  • betas 中通常需要指定对应的 beta 标签以启用 Skills 功能

4.2.2 列出和管理 Skill

可以列出当前 Workspace 可用的所有 Skill（包括 Anthropic 提供的和自定义的）：

skills = client.beta.skills.list()
for s in skills.data:
print(s.id, s.display_title, s.version)

一般工作流：

  1. 在本地写好 Skill 目录
  2. 通过 API 上传，获得 skill_id（及可选 version）
  3. 在调用 messages.create 时，将 Skill 作为 容器 / code-exec 配置的一部分传入

4.2.3 在 Messages API 中挂载 Skill

官方文档说明：Skills 是通过 code execution tool + container 与 Messages API 集成的，你可以在一次请求中挂载最多 8 个 Skill。[^skills-guide]

伪代码示例（具体字段会随着 API 演进略有不同，以下强调概念）：

message = client.messages.create(
model=”claude-3.7-sonnet”,
max_tokens=2048,
# 按需开启 Skills beta
betas=[“skills-2025-10-02”],
messages=[
{“role”: “user”, “content”: “请用 Financial Analysis 技能帮我分析这份报表”}
],
# 简化版示意：通过 code-exec 容器挂载 Skill
# 实际字段名称以官方文档为准
extra_headers={
“x-claude-container”: {
“type”: “skill”,
“skill_id”: skill.id,
# 可选地固定版本
“version”: skill.version,
}
},
)

概念要点：

  • 对 Claude 来说：
    • Skill 是运行在 代码执行容器 上的一组文件
    • 它可以在容器中：
      • 读取 SKILL.md、脚本、参考资料
      • 运行脚本（Python/Bash 等）
  • 对你来说：
    • Skill 是一种把复杂“代码 + 文档”打包后挂到 Claude 上的方式
    • 从而在应用层只需：
      • 指定 skill_id（和可选版本）
      • 然后用自然语言提示 Claude 使用某个 Skill 即可

4.3 在 Claude.ai Web UI 中使用

对于 Claude.ai 的网页版（面向终端用户）：

  • Anthropic 会提供一些“官方预置 Skill”
  • 对于企业 / Workspace 用户：
    • 也可以上传自定义 Skill 并在组织内部共享
  • 用户在 UI 中表现为：
    • 类似“应用 / 模板 / 技能”的入口
    • 或在对话中由 Claude 自动判断是否使用某个 Skill

从程序员角度，更重要的是理解：

  • 同一个 Skill，可以通过：
    • Claude Code（开发者 IDE）
    • Claude API（应用集成）
    • Claude Web（终端用户界面）
  • 以不同方式暴露出来，但底层都是同一套 SKILL.md + 资源/脚本。

4.4 Skill、Claude、MCP 的协同调用（时序图）

下面用 Mermaid 时序图展示一个常见场景：

用户请求“根据 Sentry 错误帮我自动审查这个 PR”，Claude 使用 sentry-code-review Skill + Sentry MCP server 的过程（概念）

这体现了几个关键点：

  • Skill 本身不一定直接访问外部 API，而是指挥 Claude 如何调用 MCP 工具
  • Skill 更关注「使用顺序」「错误处理策略」「输出格式」

4.5 常见使用模式与反模式

推荐模式：

  • 一个 Skill 对应一类业务任务（如“报表分析”“代码审查”“日志排障”）
  • Skill 内只描述“做什么 & 怎么做”，把“用什么工具”留给底层 Tools/MCP
  • Skill 通过 frontmatter + 正文中的“使用条件”进行自解释选择

不推荐模式：

  • 把 Skill 写成“巨型 Prompt”，什么都塞进去：
    • 难以复用，也难以调试
  • 在 Skill 中硬编码太多环境假设：
    • 如写死某个文件路径、某个组织 ID，而不是通过输入参数 / 上下文确定
  • 把敏感逻辑/凭证直接写进 SKILL.md：
    • 凭证管理一定要放在工具 / MCP 层，由服务端安全地注入

5. 综合实践建议（面向程序员）

5.1 从「工具」到「技能」的演化路线

  1. 先做 API / MCP server
    • 把外部系统能力暴露为正式的工具接口
    • 写好参数 schema、错误码、访问控制
  2. 然后设计技能层
    • 用 SKILL.md 把业务流程写成步骤
    • 在步骤里描述：在什么条件下调用哪个工具
  3. 最后接入应用 / UI
    • 在 Claude Code 上提升开发体验
    • 在 Claude API 上为终端用户提供一键式能力

5.2 版本控制与协作

  • 把 .claude/skills/ 当成普通代码目录管理：
    • 用 Git 管理版本
    • Review Skill 的改动（尤其是描述和边界条件）
  • 对于 API 上传的 Skill：
    • 使用官方版本号字段固定版本，避免生产环境被“悄悄更新”的 Skill 影响
    • 可以在 frontmatter 中增加自定义 version 字段配合管理

5.3 安全与信任

官方文档明确建议：只使用可信来源的 Skill（自己写的或 Anthropic 提供的）。

  • Skill 虽然多为“文档 + 指令”，但可能：
    • 引导 Claude 运行脚本
    • 调用 MCP 工具（进而访问敏感系统）
  • 最基本的安全策略：
    • 审查 SKILL.md：看它在干什么、调用了哪些脚本/工具
    • 审查 scripts/ 目录：看是否有危险操作（rm -rf、数据导出等）
    • 在生产环境中：
      • 对 MCP 工具和下游服务做权限分级

6. 小结：4 个核心问题回顾

6.1 什么是 Skill？

  • 是一个基于开放标准的、可移植的「Agent 能力模块」
  • 由 SKILL.md（frontmatter + 指令）和可选资源/脚本组成
  • 把领域知识、流程、边界条件固化下来，让 Claude 可以稳定复用

6.2 Skill 和 Tools 有何区别？

  • Tool = 原子能力（函数 / API）
  • Skill = 使用这些能力完成特定任务的 Playbook
  • Skill 通常通过 code-exec + MCP 工具实际访问外部世界

6.3 如何书写 Skill？

  • 按规范创建目录：<skill-name>/SKILL.md + 可选 scripts/、references/
  • 在 frontmatter 中写好 name + description（包含使用场景）
  • 在正文中结构化地写：目标、输入输出、步骤、边界情况、示例
  • 如有 MCP / 工具，明确写清楚何时调用哪些工具

6.4 如何使用 Skill？

  • 在 Claude Code 中：
    • 放到 .claude/skills/，通过 /命令 或普通自然语言触发
  • 在 Claude API 中：
    • 使用 beta.skills.create 上传
    • 在 messages.create 请求中将 Skill 作为容器挂载
  • 在 Claude.ai / 其他 Agent 平台中：
    • 通过 UI 或 Agent 配置，将 Skill 暴露给终端用户
By 工作学习