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

Skills根本不是你想的那样！

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

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

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

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

&gt; 帮我从 report.pdf 提取文字

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

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

你看到的

$ claude
Claude Code v1.0.0
Ready.
&gt;

实际发生的（抓包内容）

Claude Code 扫描了这些目录：

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

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

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

读取 SKILL.md 的头部：

---
name: pdf
description: 从 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 （用户可见）：

&lt;command-message&gt;正在加载 "pdf" skill&lt;/command-message&gt;
&lt;command-name&gt;pdf&lt;/command-name&gt;

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

你是一个 PDF 处理专家。

## 工作流程

### 步骤 1: 检查文件
使用 Read 工具检查 PDF 文件是否存在
...
(完整 800 行)

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

你在界面上看到

&gt; 帮我从 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": "&lt;command-message&gt;正在加载 \"pdf\" skill&lt;/command-message&gt;"
      // 这条你能看到 ↑
    },
    {
      "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 返回结果给你

你看到的

&gt; 帮我从 report.pdf 提取文字

正在加载 "pdf" skill

✓ 已从 report.pdf 提取文字

内容如下:

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

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

为什么Skill高效又节省呢？

没有 Skill 的情况

你需要这样说：

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

每次都要重复这些指令！

API 请求（每次都发）：

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

Token： ~80 tokens × 每次使用

有 Skill 的情况

你只需要说：

&gt; 帮我从 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&lt;skills_instructions&gt;\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively...\n\n&lt;available_skills&gt;\n\"pdf\": 从 PDF 提取文字和表格。当用户提到 PDF、文档提取时使用\n\"xlsx\": 创建和编辑 Excel 文件\n&lt;/available_skills&gt;",
      "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 行内容不在这里只有一行描述

所以Skills 到底是怎么工作的？

就这几步：

启动时：扫描所有 skills，只读前几行(name + description）
发请求时：把所有 skills 的简短描述塞进 “Skill” 工具里
Claude 匹配：用 AI 理解能力匹配用户意图和 skill 描述
激活 skill：读取完整的 SKILL.md，注入到对话中
执行： Claude 按照注入的指令工作，工具预批准，不用确认

这种架构的设计核心优势：

不用的 skill 不加载完整内容，可以有 100 个 skills，只占 2000 tokens，所有 skills 格式一样，容易分享安全，工具权限仅在 skill 执行时有效。

https://link.bytenote.net/tvfkjl

希望这次够具体了！

文章目录

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

所以Skills 到底是怎么工作的？

See Also

最近文章

福利派送

分类

标签

友情链接

其它