Token 节省利器：Claude Agent Skills 使用与原理解析

在大语言模型（LLM）向通用 Agent 演进的进程中，“领域专业化能力”与“上下文效率”始终是核心矛盾——将全领域知识嵌入系统提示会引发令牌冗余、响应延迟，而精简提示又会导致模型丧失专业判断能力。Claude Agent Skills 正是为破解这一矛盾而生：它以“模块化技能包”为载体，将特定领域的指令、脚本与资源封装为可动态加载的单元，让通用LLM在需要时快速切换为领域专家，同时最大限度节省上下文资源。本文将从实战应用切入，逐步深入Skills的创建规范与底层工作原理，助力开发者真正掌握这一拓展Claude能力边界的核心工具。

一. 如何使用 Claude Agent Skills

1.1 Agent Skills加载路径

Claude Code（及 Claude 桌面端）会扫描三个层级的路径来发现可用技能，不同路径对应不同的使用范围，开发者可根据需求选择存储位置：

个人全局路径（~/.claude/skills/）：适用于个人常用的通用技能，如 PDF 处理、代码格式化等，一次存储即可在所有项目中使用。例如将 pdf-skill 文件夹放入此路径后，无论在哪个项目中请求 “提取 PDF 文本”，Claude 都能识别到该技能。
项目局部路径（.claude/skills/）：需在项目根目录下创建该文件夹，存放与项目强相关的技能，如特定业务的数据分析模板、团队文档规范检查等。这类技能仅在当前项目中生效，避免全局技能泛滥。
插件路径：通过 Claude 插件市场安装的技能会自动放入预设插件目录，无需手动管理，适合快速试用官方或第三方提供的成熟技能（如 Anthropic 开源的skill-creator、nda-review等）。

无论选择哪种路径，技能的核心要求是：每个技能必须是一个独立文件夹，且根目录下存在 SKILL.md 文件，这是 Claude 识别技能的唯一标识，缺少该文件的文件夹会被视为普通资源，无法被加载为技能。

1.2 尝鲜 Agent Skills

GitHub 上目前有丰富的开源Agent Skills资源，Anthropic官方也提供了多款技能可供直接使用：anthropics/skills

我们只需将该仓库克隆至本地，再将所需技能拷贝至项目的 .claude/skills/ 目录或用户目录 ~/.claude/skills/ 下即可：

# clone anthropic 官方提供的常用的skills
git clone git@github.com:anthropics/skills.git
# 将需要的skills目录拷贝至 ~/.claude/skills/
cp -r skills/pdf/ ~/.claude/skills

重启Claude Code后，输入skills命令即可查看已成功注册的PDF技能：

Claude Code 是在启动时加载的Agent Skills，所以新增 Skills 后需要重启 Claude Code。

当尝试拆分PDF文件时，Claude Code会基于 pdf skill 的 SKILL.md 文件元数据，识别到可通过该技能完成任务，并询问是否启用该技能：

选择“Yes”执行技能后，Claude会尝试运行技能包中的Python脚本。若为首次运行且未安装依赖，Claude会根据报错信息自动安装所需的Python依赖：

依赖安装完成后，Claude会再次调用脚本，执行PDF拆分操作：

二. Agent Skills 规范

掌握技能的使用方法后，下一步即可创建贴合自身需求的自定义技能。Claude Agent Skills的设计遵循“结构化、可扩展”原则，核心在于SKILL.md文件与标准化目录结构，开发者只需遵循规范，就能将任意领域的专业流程封装为可复用技能。

2.1 目录结构

基础结构(简单 Skill):

1 2	skill-name/ └── SKILL.md

标准结构(推荐):

skill-name/
├── SKILL.md               # 必须：Skill 元数据和核心指令
├── scripts/               # 可选：可执行代码（Python/Shell等）
├── references/            # 可选：可按需加载至上下文的参考文档            
└── assets/                # 可选：用于输出内容的文件

2.2 `SKILL.md` 规范

自定义技能的核心是 “一份 SKILL.md + 可选的辅助资源”，其中 SKILL.md 是技能的 “大脑”，定义了技能的元数据、执行指令与资源引用，而辅助资源则负责扩展技能的功能边界（如脚本处理确定性任务、参考文档提供专业知识）。

SKILL.md 采用 “元数据 + 指令” 的双段结构，前者用于 Claude 识别技能，后者用于指导 Claude 执行任务，两者缺一不可。

2.2.1 YAML Frontmatter

Frontmatter（元数据）：位于SKILL.md开头，用---包裹，是 Claude 发现与触发技能的关键。

Claude 在启动时加载此元数据并将其包含在系统提示中。这种轻量级方法意味着您可以安装许多 Skills 而不会产生上下文成本；Claude 只知道每个 Skill 的存在以及何时使用它。

元数据包含必填与可选字段：

---
name: skill-name-here
description: 清楚地描述这个技能的作用和何时激活它
---

字段规范:

字段	要求	说明
`name`	小写字母、数字、短横线,≤64字符	必须与目录名一致
`description`	纯文本，≤1024字符	用于检索和激活
`license`	可选，许可协议信息。
`allowed-tools`	可选，定义该技能可自动使用的工具列表，无需用户每次批准。
`model`	可选，指定执行该技能的模型版本。默认继承当前会话模型，但对于代码审查等复杂任务，可指定更强大的模型。
`disable-model-invocation`	可选，如果设置为 `true`，Claude 将不会自动调用该技能。这适用于需要用户显式通过 `/skill-name` 触发的高风险操作或配置命令。

Description 技巧:

# ❌ 过于泛化
description: 帮助完成代码任务

# ✅ 具体且包含关键词
description: 处理CSV文件，生成带图表的Excel报表。当用户要求转换数据格式或创建可视化报告时使用。

# ✅ 说明触发场景
description: 使用bandit分析Python代码中的安全漏洞。当用户提到“安全审计”或“漏洞扫描”时激活。

2.2.2 Markdown 正文（执行指令）

Frontmatter 之后的Markdown正文，是 Claude Code 调用技能时实际读取的提示内容（Prompt），用于定义技能的执行逻辑、操作步骤与输出规范。编写高效提示的核心是简洁性与渐进式披露：在SKILL.md中仅保留核心指令，细节内容通过外部文件引用加载。

---
# 文档前置信息
---

# [简要用途说明 - 1–2 句话]

## 概述
[描述此技能的功能、使用场景及所提供的价值]

## 前置条件
[列出所需的工具、文件或上下文]

## 操作步骤

### 步骤 1：[第一步操作]
[使用祈使句给出明确指令]
[必要时提供示例]

### 步骤 2：[下一步操作]
[使用祈使句给出明确指令]

### 步骤 3：[最后一步操作]
[使用祈使句给出明确指令]

## 输出格式
[说明结果应如何组织]

## 错误处理
[当出现问题时的应对措施]

## 示例
[提供具体的使用示例]

## 相关资源
[引用随附的 scripts/、references/、assets/ 等内容]

提示内容编写最佳实践：
- 控制篇幅：建议控制在 5000 字（约 800 行）以内，避免上下文过载。
- 使用指令性语言：直接使用祈使句（如“分析代码以发现…”），避免冗长的第二人称描述（如“你应该…”）。
- 引用外部文件：将详细文档、规范或长文本移至外部文件，通过引用加载。
- 使用相对路径：始终使用 {baseDir} 变量指定路径，严禁硬编码绝对路径（如 /home/user/project/）。

当技能被激活时，Claude 将获得 allowed-tools 中指定工具的访问权限，并根据配置加载相应的模型。技能的根目录路径会自动注入，确保能够正确访问所有绑定的资源。

2.3 辅助资源的组织与绑定

为充分发挥技能的潜力，通常需将辅助资源与SKILL.md打包整合。推荐的标准目录结构包含以下三个子目录，各司其职且便于维护：

my-skill/
├── SKILL.md              # 核心提示词与指令
├── scripts/              # 可执行脚本 (Python/Bash)
├── references/           # 需加载到上下文的参考文档
└── assets/               # 静态资源与模板

为什么要进行资源打包？ 资源打包的核心目的是保持 SKILL.md 的精简（建议不超过 5000 字），防止无效信息占用 Claude 的上下文窗口。通过将详细文档、脚本和模板分离，Claude 可以利用渐进式披露技术，仅在真正需要时加载特定资源。

scripts/：存放 Claude 可通过 Bash 工具调用的可执行代码。包括自动化脚本、数据处理程序、验证器或代码生成器，用于执行确定性任务。
references/：存放 Claude 在需要时会读取到上下文中的参考文档。包括 Markdown 指南、JSON Schema、API 规范、检查清单等。凡是对于 SKILL.md 来说过于冗长，但对任务执行又必不可少的文本内容，都应放入此处。
assets/：存放 Claude 可以引用但通常不会直接加载到上下文中的静态文件。包括 HTML/CSS 模板、图片、字体或二进制文件。

三. Agent Skills原理

3.1 核心设计理念

Agent Skills 本质上是一个包含指令、脚本和资源的标准化目录结构。Agent 能够动态发现并加载这些资源，从而获得完成特定任务所需的能力。通过将专业知识封装为可组合的资源包，Skills 极大地扩展了 Claude 的功能边界，将其从一个通用代理转变为能够适应特定需求的专用代理。

形象地说，为智能体构建技能就像是为新员工编写一份详尽的入职指南。借助于 Skills，我们无需再为每个特定场景构建孤立的、定制化的智能体。相反，任何人都能够通过捕获和共享流程知识，为智能体灵活添加功能模块。本文将深入解析 Skills 的定义、工作原理，并分享构建高质量 Skills 的最佳实践。

3.2 渐进式披露

Agent Skills最核心的创新的是渐进式披露（Progressive Disclosure）机制。该机制将技能信息分为三个层级，智能体按需逐步加载，既保证必要时不遗漏细节，又避免一次性加载过多内容导致上下文臃肿：

级别	加载时间	令牌成本	内容
第 1 级：元数据	始终（启动时）	每个 Skill 约 100 个令牌	YAML 前置数据中的 `name` 和 `description`
第 2 级：指令	技能被触发时	不到 5k 个令牌	包含指令和指导的 SKILL.md 主体
第 3 级+：资源	执行过程中按需加载	实际上无限制	通过 bash 执行的捆绑文件，不将内容加载到上下文中

第一层：元数据（Metadata）

智能体启动时，会扫描所有已安装的技能文件夹，仅读取每个 SKILL.md 的 Frontmatter 部分，并将这些元数据加载至系统提示中。实测数据显示，每个技能的元数据仅消耗约100个令牌，即便安装50个技能，初始上下文消耗也仅约5000个令牌，对性能影响极小。

这与MCP（模型上下文协议）的工作方式形成显著差异：典型的MCP实现中，客户端连接服务器时，通常需通过tools/list请求获取所有工具的完整JSON Schema，可能瞬间消耗数万个令牌，上下文成本显著更高。

第二层：技能主体（Instructions）

当智能体通过分析用户请求，判定某一技能与当前任务高度匹配时，会触发第二层加载——读取该技能SKILL.md的完整正文内容，将详细指令、注意事项、示例等加载至上下文。

此时，智能体已获取完成任务所需的全部上下文（如数据库结构、操作规范、输出要求等）。这部分内容的令牌消耗取决于指令复杂度，通常在1000至5000个令牌之间，处于可控范围。

第三层：附加资源（Scripts & References）

对于复杂技能，SKILL.md可引用同一文件夹下的其他资源，智能体仅在执行过程中按需加载这些内容。

例如，一个PDF处理技能的文件结构如下：

skills/pdf-processing/
├── SKILL.md              # 主技能文件
├── parse_pdf.py          # PDF 解析脚本
├── forms.md              # 表单填写指南（仅在填表任务时加载）
└── templates/            # PDF 模板文件
    ├── invoice.pdf
    └── report.pdf

在 SKILL.md 中，可以这样引用附加资源：

当需要执行 PDF 解析时，智能体会运行 parse_pdf.py 脚本
当遇到表单填写任务时，才会加载 forms.md 了解详细步骤
模板文件只在需要生成特定格式文档时访问

这种设计有两个关键优势：

无限的知识容量：通过脚本和外部文件，技能可以”携带”远超上下文限制的知识。例如，一个数据分析技能可以附带一个 1GB 的数据文件和一个查询脚本，智能体通过执行脚本来访问数据，而无需将整个数据集加载到上下文中。
确定性执行：复杂的计算、数据转换、格式解析等任务交给代码执行，避免了 LLM 生成过程中的不确定性和幻觉问题。

四. 实战：创建 “微信公众号文章生成技能”

以 “生成符合微信生态的公众号文章” 为例，完整演示自定义技能的创建流程，最终实现 “用户提供主题后，自动生成 SEO 标题、结构化大纲与正文” 的功能。

4.1 创建技能目录

1 2	mkdir -p .claude/skills/wechat-article-generator cd .claude/skills/wechat-article-generator

4.2 编写`SKILL.md`

首先定义 YAML Frontmatter，明确技能的元数据：

---
name: wechat-article-generator
description: 生成符合微信生态的公众号文章，支持SEO标题优化、痛点-方案-行动结构的正文撰写及配图占位符插入，当用户需要创作公众号内容、优化现有文章或生成文章大纲时使用。
allowed-tools: "Read,Write,Bash(python:*)"
model: "Claude 3 Sonnet"
license: "MIT License"
---

接着编写 Markdown 正文，提供详细执行指令：

# 微信公众号文章生成指南

## 概述
本技能用于生成符合微信用户阅读习惯的公众号文章，核心关注标题打开率、正文可读性与内容转化率，适用于科技、职场、生活类主题。

## 前置条件
1. 用户需提供文章主题（如“职场高效沟通技巧”）；
2. 若需优化现有文章，用户需提供文章文本或文件路径；
3. 确保Bash工具已启用，以运行标题生成脚本。

## 操作步骤
1. **需求分析**：提取用户提供的主题关键词（如“职场”“沟通技巧”），判断文章类型（干货、故事、观点），确定目标读者（如职场新人、管理者）。
2. **标题生成**：
   - 运行`./scripts/generate-titles.py <主题关键词>`，生成10个SEO标题候选；
   - 筛选符合“数字+痛点+解决方案”结构的标题（如“5个职场沟通技巧，帮你避免无效对话”），保留3个最优选项供用户选择。
3. **大纲创建**：
   - 按“引言（痛点引入）→ 核心内容（分3-5点，每点含案例）→ 总结（行动建议）”结构生成大纲；
   - 每个核心要点需包含“观点+案例+数据/引用”，增强说服力。
4. **正文撰写**：
   - 基于选定的标题与大纲，按每段不超过300字的标准撰写正文；
   - 关键观点用加粗标注，复杂概念用“类比”解释（如“职场沟通就像拼图，需先明确对方的‘拼图需求’”）；
   - 在正文合适位置插入配图占位符（如`[配图：职场沟通场景示意图]`），标注图片主题与尺寸（建议900*500px）。
5. **质量检查**：
   - 检查标题是否包含关键词，正文是否符合“痛点-方案-行动”结构；
   - 确保无“众所周知”“大家都知道”等模糊表述，数字需明确来源（如“据LinkedIn 2024职场报告显示”）。

## 错误处理
1. 若用户仅提供模糊主题（如“写一篇关于沟通的文章”），需追问补充信息（如“目标读者是学生还是职场人？希望侧重理论还是实操？”）；
2. 若标题生成脚本运行失败，检查Python环境是否正常，或手动按“数字+痛点”结构生成标题；
3. 若文章主题涉及敏感领域（如医疗、法律），提示用户需补充专业信息，避免生成不准确内容。

## 资源引用
- 详细的SEO标题模板见`./references/seo-templates.md`；
- 公众号排版规范（字体、行间距）见`./references/typesetting-guidelines.md`；
- 配图设计建议见`./assets/cover-template-readme.md`。

4.3 添加辅助资源

创建scripts/generate-titles.py脚本，实现标题自动生成：

import sys
import random

def generate_titles(theme):
    # 定义SEO标题模板，包含数字、痛点、解决方案
    templates = [
        "{num}个{theme}技巧，帮你解决{pain}问题",
        "为什么你做不好{theme}？{num}个关键方法带你突破",
        "{theme}避坑指南：{num}个错误别再犯，效率提升{rate}",
        "从0到1学{theme}：{num}个实操步骤，新手也能上手"
    ]
    # 痛点与数字、效率的候选值
    pains = ["职场沟通", "无效对话", "表达不清", "信息传递"]
    nums = [3, 5, 7, 10]
    rates = ["50%", "80%", "100%"]
    
    titles = []
    for template in templates:
        title = template.format(
            num=random.choice(nums),
            theme=theme,
            pain=random.choice(pains),
            rate=random.choice(rates)
        )
        titles.append(title)
    return titles

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法：python generate-titles.py <主题关键词>")
        sys.exit(1)
    theme = sys.argv[1]
    titles = generate_titles(theme)
    print("生成的SEO标题候选：")
    for i, title in enumerate(titles, 1):
        print(f"{i}. {title}")

创建references/seo-templates.md，补充标题模板细节：

# 公众号文章SEO标题模板

## 干货类主题
- 结构：数字+技巧/方法+痛点解决（如“7个Excel快捷键，帮你节省80%制表时间”）
- 关键词位置：尽量将核心关键词（如“Excel快捷键”）放在标题前半部分

## 故事类主题
- 结构：场景+冲突+悬念（如“入职3个月被提拔：他做对了这1件事”）
- 注意：避免剧透，保留“用户想点击查看答案”的悬念

## 观点类主题
- 结构：反常识观点+理由暗示（如“‘努力就能成功’是误区：职场晋升的3个隐性逻辑”）
- 优势：反常识观点易引发用户讨论，提升转发率

4.4 使用官方 `skill-creator`

anthropic官方提供了 skill-creator 工具，我们可以用该 skill 创建一个属于我们自己业务领域的 skill：

我们将 skill-creator 拷贝到全局skills目录中：

1	cp -r skills/skill-creator ~/.claude/skills

重启 Claude Code，使用自然语言创建 Claude Code：

五. Agent Skills 和 MCP关系

Agent Skills 和 MCP 代表了智能体技术栈中两个关键的抽象层：

MCP（Model Context Protocol）：解决”连接性”问题，是智能体与外部世界交互的标准化接口，相当于”神经系统”或”双手”，MCP是通过标准流程，降低LLM调用外部工具的开发成本。
Agent Skills：解决”能力”问题，是领域知识和工作流的封装，相当于”大脑皮层”或”操作手册”。

两者不是竞争关系，而是互补关系：

六. 总结

本文围绕 Claude Agent Skills 展开全方位解析，核心聚焦其 “破解通用 LLM 领域专业化与上下文效率矛盾” 的核心价值，形成从应用到创作、从规范到原理的完整知识闭环：

核心定位：Claude Agent Skills 是模块化技能包，通过 “元数据 + 指令 + 辅助资源” 的结构化封装，让通用 LLM 按需加载专业能力，兼顾领域深度与上下文效率。
关键应用：支持个人全局、项目局部、插件三类加载路径，需以含 SKILL.md 的独立文件夹为载体，可通过克隆开源仓库快速使用 PDF 处理、代码优化等现成技能。
创建规范：遵循 “SKILL.md 核心 + scripts/references/assets 辅助” 的目录结构，YAML 元数据负责技能识别，Markdown 正文定义执行逻辑，辅助资源分别承载可执行脚本、专业文档与静态模板。
底层原理：以渐进式披露机制为核心，通过元数据（启动加载）、技能主体（触发加载）、附加资源（按需加载）三级策略，平衡令牌成本与能力深度；与 MCP 形成互补，分别解决 “能力封装” 与 “外部连接” 问题。
核心价值：实现专业流程的标准化沉淀与复用，降低智能体定制成本，推动 LLM 从 “单次任务响应” 走向 “组件化能力拓展”，为个人、团队与企业级场景提供高效的智能解决方案。

参考文章：

Agent Skills - Claude Docs

CC Academy - Claude Agent Skills 第一性原理深度解析

Claude Agent Skills 深度解析：原理、工作流与最佳实践 | ApFramework

hello-agents/Extra-Chapter/Extra05-AgentSkills解读.md at main · datawhalechina/hello-agents

一文讲清楚Claude Agent Skills篇，如何自定义Skills - 知乎

YYH211/Claude-meta-skill