我要投稿

Skills根本不是你想的那样!一个真实案例看懂 Skills 全流程

发布日期：2026-01-01 16:12:02 浏览次数： 2122

作者：字节笔记本

微信搜一搜，关注“字节笔记本”

Skills根本不是你想的那样！

Han Lee 通过抓包和逆向工程从第一性原理深度解析 Claude Agent Skills 系统的内部架构与工作机制，还原了Skills的运行原理（原文链接见文末）

一句话：Claude Skills 并非可执行代码，而是一套基于 prompt 注入的元工具架构。

原文包含了大量的图表和概念，理解起来还是会有一些些困难的，所以我另外再结合官方的仓库提供的SkillA社自家的Claude Skills 仓库都有哪些宝贝技能？将流程进行了进一步的简化，相信会让你对于Skills 全流程有一个更清晰的了解。

在使用官方Skill处理一个 PDF 文件时，你在终端输入：

> 帮我从 report.pdf 提取文字

现在我们来看背后到底发生了什么。

第一步:Claude Code 启动时做了什么

你看到的

$ claude
Claude Code v1.0.0
Ready.
>

实际发生的（抓包内容）

Claude Code 扫描了这些目录：

~/.claude/skills/# 你的个人 skills.claude/skills/# 项目 skillsplugins/*/skills/# 插件提供的 skills

找到了一个 pdf skill，文件结构：

~/.claude/skills/pdf/
├── SKILL.md# 主文件
├── scripts/
│ └── extract.py# Python 脚本
└── references/
└── api-docs.md # API 文档

读取 SKILL.md 的头部：

---name: pdfdescription: 从 PDF 提取文字和表格。当用户提到 PDF、文档提取时使用allowed-tools: Bash(python:*), Read, Write---

注意这里只读这几行！ 完整的 SKILL.md 有 800 行，但现在不读。

第二步：你的请求发送到 Claude

实际的 HTTP 请求简化后的版本如下：

POST https://api.anthropic.com/v1/messages{
"model": "claude-sonnet-4-5",
"messages": [{"role": "user","content": "帮我从 report.pdf 提取文字"}
],
"tools": [{"name": "Skill","description": "执行一个 skill\n\n可用的 skills:\n\"pdf\": 从 PDF 提取文字和表格。当用户提到 PDF、文档提取时使用\n\"excel\": 创建和编辑 Excel 文件\n\"ppt\": 创建演示文稿","input_schema": {"type": "object","properties": {"command": {"type": "string"}}}},{"name": "Bash","description": "执行 bash 命令","input_schema": {...}},{"name": "Read","description": "读取文件","input_schema": {...}}
]}

关键点：

pdf skill 的 800 行内容没有发送
只发送了描述："从 PDF 提取文字和表格。当用户提到 PDF、文档提取时使用"
这只有 20 个 token

第三步:Claude 决定调用 pdf skill

Claude 的响应（抓包内容）

{
"content": [{"type": "text","text": "我会帮你从 PDF 中提取文字。"},{"type": "tool_use","id": "toolu_abc123","name": "Skill","input": {"command": "pdf"}}
]}

Claude 的思考过程，我们看不到，大概它这么想的：

用户说 "从 report.pdf 提取文字"
→ 关键词: PDF, 提取, 文字
→ 看看我有什么工具...
→ "Skill" 工具里有 "pdf": 从 PDF 提取文字和表格
→ 完美匹配!
→ 调用 Skill 工具,command="pdf"

第四步：执行 Skill 工具（这里是重点了！）

Claude Code 收到 Claude 要调用 Skill（"pdf"）

现在才读取完整的 SKILL.md(800 行）：

---
name: pdf
description: 从 PDF 提取文字和表格allowed-tools: Bash(python:*), Read, Write
---

# PDF 处理专家

你是一个 PDF 处理专家。

## 工作流程

### 步骤 1: 检查文件
使用 Read 工具检查 PDF 文件是否存在

### 步骤 2: 提取文字
运行脚本:

python {baseDir}/scripts/extract.py report.pdf

### 步骤 3: 读取结果
Read 工具读取 output.txt

### 步骤 4: 展示给用户

## 可用工具
- Bash(python:*) - 运行 Python 脚本
- Read - 读取文件
- Write - 保存结果

基础目录: {baseDir}

准备发送给 Claude 的两条消息：

消息 1 （用户可见）：

<command-message>正在加载 "pdf" skill</command-message><command-name>pdf</command-name>

消息 2 （用户看不见，但发给 API）：

你是一个 PDF 处理专家。## 工作流程### 步骤 1: 检查文件使用 Read 工具检查 PDF 文件是否存在
...
(完整 800 行)

第五步：发送增强后的请求给 Claude

你在界面上看到

> 帮我从 report.pdf 提取文字

正在加载 "pdf" skill

实际发送的完整 HTTP 请求

POST https://api.anthropic.com/v1/messages{
"model": "claude-sonnet-4-5",
"messages": [{"role": "user","content": "帮我从 report.pdf 提取文字"},{"role": "assistant","content": [{"type": "text", "text": "我会帮你从 PDF 中提取文字。"},{"type": "tool_use", "name": "Skill", "input": {"command": "pdf"}}]},{"role": "user","content": "<command-message>正在加载 \"pdf\" skill</command-message>"// 这条你能看到 ↑},{"role": "user","content": "你是一个 PDF 处理专家。\n\n## 工作流程\n\n### 步骤 1: 检查文件...","isMeta": true// ↑ 这条你看不到,但发给了 Claude!// 完整 800 行都在这里!},{"role": "user","content": {"type": "command_permissions","allowedTools": ["Bash(python:*)", "Read", "Write"]}// ↑ 这个告诉系统:这些工具预先批准了}
]}

Token 对比：

第一次请求： ~50 tokens （只有描述）
第二次请求： ~2,000 tokens （完整 skill 内容）

第六步:Claude 按照 skill 指令执行

现在 Claude 的"记忆"里有：
1.用户原始请求："帮我从 report.pdf 提取文字"
2. 新注入的指令："你是一个 PDF 处理专家。按照以下步骤。。。"
3. 预批准的工具： Bash(python:*)， Read， Write

Claude 开始工作

第 1 个工具调用 - 检查文件：

{
"type": "tool_use",
"name": "Read",
"input": {"path": "report.pdf","description": "检查 PDF 文件是否存在"
}}

系统返回：

{
"type": "tool_result",
"content": "文件存在,大小 1.2MB"}

第 2 个工具调用 - 运行 Python 脚本：

{
"type": "tool_use",
"name": "Bash",
"input": {"command": "python ~/.claude/skills/pdf/scripts/extract.py report.pdf","description": "提取 PDF 文字"
}}

这个调用不需要用户确认！
为什么？因为 Bash(python:*) 在 allowed-tools 里被预批准了！

系统执行脚本，返回：

{
"type": "tool_result",
"content": "提取完成,输出保存到 output.txt"}

第 3 个工具调用 - 读取结果：

{
"type": "tool_use",
"name": "Read",
"input": {"path": "output.txt"
}}

{
"type": "tool_result",
"content": "这是一份关于 2024 年度财务报告...\n\n总收入: 1000 万美元\n..."}

第七步:Claude 返回结果给你

你看到的

> 帮我从 report.pdf 提取文字

正在加载 "pdf" skill

✓ 已从 report.pdf 提取文字

内容如下:

这是一份关于 2024 年度财务报告

总收入: 1000 万美元
总支出: 800 万美元
净利润: 200 万美元
...

为什么Skill高效又节省呢？

没有 Skill 的情况

你需要这样说：

> 用 pdftotext 命令从 report.pdf 提取文字,
> 然后读取输出文件,
> 如果遇到错误要处理,
> 最后格式化显示给我

每次都要重复这些指令！

API 请求（每次都发）：

{
"messages": [{"role": "user","content": "用 pdftotext 命令从 report.pdf 提取文字,然后读取输出文件,如果遇到错误要处理,最后格式化显示给我"}
]}

Token： ~80 tokens × 每次使用

有 Skill 的情况

你只需要说：

> 帮我从 report.pdf 提取文字

第一次 API 请求（只发描述）：

{
"tools": [{"name": "Skill","description": "...\"pdf\": 从 PDF 提取文字和表格..."
}]}

Token： ~20 tokens

第二次 API 请求（发完整指令）：

{
"messages": [...,{"content": "你是 PDF 专家...(完整 800 行)", "isMeta": true}
]}

Token： ~2,000 tokens × 只在激活时发一次

算下来你要处理 10 个 PDF

没有 Skill：

10 次 × 80 tokens = 800 tokens

有 Skill：

启动时: 20 tokens (描述)
第 1 次激活: 2,000 tokens (完整指令)
后续 9 次: 0 tokens (已在上下文中)
总计: 2,020 tokens

但实际上，Skill 会在对话过程中被压缩，所以后续调用可能会重新加载。

如果你真的抓包 Claude Code，你会看到：

请求头：

POST /v1/messages HTTP/1.1
Host: api.anthropic.com
anthropic-version: 2023-06-01
content-type: application/json
x-api-key: sk-ant-...

请求体（关键部分）：

{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"tools": [{"name": "Skill","description": "Execute a skill within the main conversation\n\n<skills_instructions>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively...\n\n<available_skills>\n\"pdf\": 从 PDF 提取文字和表格。当用户提到 PDF、文档提取时使用\n\"xlsx\": 创建和编辑 Excel 文件\n</available_skills>","input_schema": {"type": "object","properties": {"command": {"type": "string","description": "The skill name (no arguments). E.g., \"pdf\" or \"xlsx\""}},"required": ["command"]}}
],
"messages": [...]}

看到了吗？pdf skill 的 800 行内容不在这里只有一行描述