为什么使用skills-附带实战(内部备份)第一章: Skills 技术深度解析 1 核心背景: 上下文工程的挑战在理

第一章: Skills 技术深度解析

1 核心背景: 上下文工程的挑战

在理解 Agent Skills 之前，必须先明确当前 Agent 开发中面临的核心痛点——上下文工程（Context Engineering）与 Token 效率。

1.1 传统模式的局限性

在现有的生态系统中（Skills 出现之前），为了赋予 Agent 广泛的能力，开发者通常需要将所有的工具定义（Tool Schemas）加载到 System Prompt 中。这些工具可能包括：

本地工具： 文件系统操作、Bash 命令执行、网页浏览、数据抓取等。
MCP (Model Context Protocol) 服务： Google Drive, Calendar, Notion, Slack 等外部集成。

存在的问题：
这种做法极度浪费 Token。

全量加载： 即使是一个简单的任务，Agent 的 System Prompt 中也包含了所有可用工具的详细文档和参数说明。
资源浪费： 例如，一个包含 20 个工具的 MCP Server，其 Schemas 和说明可能占用 3,000 Tokens。但在单次对话中，Agent 可能只使用了其中不到 10% 的功能。
上下文挤压： 过多的工具定义占据了宝贵的上下文窗口，限制了处理复杂任务的能力。

1.2 Skills 的解决方案

Skills 的设计初衷就是为了解决上述的上下文工程问题。其核心机制是将静态的“全量加载”转变为动态的“按需加载”。

2 Skills的架构与解剖

从物理结构上讲，Skill 的实现非常轻量化。它不需要复杂的服务器架构，本质上只是一个包含特定 Markdown 文件的文件夹。

2.1 文件目录结构

一个最小化的 Skill 单元只需要一个文件夹和一个核心定义文件：

MySkill/                <-- Skill 根目录
├── skill.md            <-- [核心] 必须存在，包含元数据和指令
├── scripts/            <-- [可选] 存放 Python 或 Bash 脚本
│   ├── validation.py
│   └── processing.sh
├── data.csv               <-- [可选] 存放 CSV, JSON 等数据文件
└── additional_context.md               <-- [可选] 额外上下文文档 (*.md, *.txt)

2.2 核心文件详解: SKILL.md (重要:文件名字必须是这样的)

SKILL.md 是 Skill 的大脑，其结构有着严格的格式要求，包含 YAML Frontmatter 和 Body 两部分。

YAML Frontmatter 元数据

位于文件顶部，用于定义 Skill 的身份。这是 Agent 在初始阶段唯一能看到的信息。

---
name: PDF_Analysis_Skill
description: 用于处理和分析 PDF 文件的技能。当用户需要从 PDF 中提取数据、总结内容或进行跨文档对比时使用此技能。
---

Name: 技能的唯一标识符。
Description: 至关重要。它类似于 Tool Description，告诉 Agent 这个技能不仅是“什么”，更是“何时”应该被调用。

Body (主体指令)

位于 Frontmatter 之后，包含详细的操作步骤、逻辑判断和上下文信息。

# PDF Analysis Instructions

当决定使用此技能时，请遵循以下步骤：
1. 检查 PDF 文件的可读性。
2. 使用 Python 脚本 `scripts/extract_text.py` 提取文本。
... [详细的技术实现细节] ...

3 设计哲学: 渐进式披露

skills 最强大的设计模式在于渐进式披露。这是实现极高 Token 效率的关键。

原理详解：
当你为一个 Agent 配置 Skill 时，系统不会将整个 skill.md 的内容加载到 System Prompt 中。

初始阶段： Agent 只能看到 YAML Frontmatter 中的 name 和 description（通常仅消耗约 50 Tokens）。

决策阶段： Agent 根据用户意图和 description 判断是否需要使用该 Skill。

加载阶段： 只有当 Agent 决定调用该 Skill 时，系统才会读取并加载 skill.md 的 Body 部分以及相关的脚本或文档内容。

这是一份基于 Anthropic Claude Agent Skills 深度解析的出版级技术讲义。本部分涵盖了核心概念、架构原理、上下文工程痛点分析以及与其他生态组件的对比（约占全篇内容的前 20%）。

第一章：Claude Agent Skills 技术深度解析

1. 核心背景：上下文工程的挑战

在理解 Agent Skills 之前，必须先明确当前 Agent 开发中面临的核心痛点——上下文工程（Context Engineering）与 Token 效率。

1.1 传统模式的局限性

本地工具： 文件系统操作、Bash 命令执行、网页浏览、数据抓取等。
MCP (Model Context Protocol) 服务： Google Drive, Calendar, Notion, Slack 等外部集成。

存在的问题：
这种做法极度浪费 Token。

全量加载： 即使是一个简单的任务，Agent 的 System Prompt 中也包含了所有可用工具的详细文档和参数说明。
资源浪费： 例如，一个包含 20 个工具的 MCP Server，其 Schemas 和说明可能占用 3,000 Tokens。但在单次对话中，Agent 可能只使用了其中不到 10% 的功能。
上下文挤压： 过多的工具定义占据了宝贵的上下文窗口，限制了处理复杂任务的能力。

1.2 Skills 的解决方案

Skills 的设计初衷就是为了解决上述的上下文工程问题。其核心机制是将静态的“全量加载”转变为动态的“按需加载”。

2. Skills 的架构与解剖 (The Anatomy of a Skill)

从物理结构上讲，Skill 的实现非常轻量化。它不需要复杂的服务器架构，本质上只是一个包含特定 Markdown 文件的文件夹。

2.1 文件目录结构

一个最小化的 Skill 单元只需要一个文件夹和一个核心定义文件：

codeText

MySkill/                <-- Skill 根目录
├── skill.md            <-- [核心] 必须存在，包含元数据和指令
├── scripts/            <-- [可选] 存放 Python 或 Bash 脚本
│   ├── validation.py
│   └── processing.sh
├── data/               <-- [可选] 存放 CSV, JSON 等数据文件
└── docs/               <-- [可选] 额外上下文文档 (*.md, *.txt)

2.2 核心文件详解：skill.md

skill.md 是 Skill 的大脑，其结构有着严格的格式要求，包含 YAML Frontmatter 和 Body 两部分。

A. YAML Frontmatter (元数据)

位于文件顶部，用于定义 Skill 的身份。这是 Agent 在初始阶段唯一能看到的信息。

codeYaml

---
name: PDF_Analysis_Skill
description: 用于处理和分析 PDF 文件的技能。当用户需要从 PDF 中提取数据、总结内容或进行跨文档对比时使用此技能。
---

Name: 技能的唯一标识符。
Description: 至关重要。它类似于 Tool Description，告诉 Agent 这个技能不仅是“什么”，更是“何时”应该被调用。

B. Body (主体指令)

位于 Frontmatter 之后，包含详细的操作步骤、逻辑判断和上下文信息。

codeMarkdown

# PDF Analysis Instructions

当决定使用此技能时，请遵循以下步骤：
1. 检查 PDF 文件的可读性。
2. 使用 Python 脚本 `scripts/extract_text.py` 提取文本。
... [详细的技术实现细节] ...

3. 设计哲学：渐进式披露 (Progressive Disclosure)

Skills 最强大的设计模式在于渐进式披露。这是实现极高 Token 效率的关键。

原理详解：
当你为一个 Agent 配置 Skill 时，系统不会将整个 skill.md 的内容加载到 System Prompt 中。

初始阶段： Agent 只能看到 YAML Frontmatter 中的 name 和 description（通常仅消耗约 50 Tokens）。

决策阶段： Agent 根据用户意图和 description 判断是否需要使用该 Skill。

加载阶段： 只有当 Agent 决定调用该 Skill 时，系统才会读取并加载 skill.md 的 Body 部分以及相关的脚本或文档内容。

对比分析：

MCP/Tools： 初始加载消耗 ~3,000 Tokens（无论是否使用）。
Skills： 初始加载消耗 ~50 Tokens -> 按需加载剩余内容。

这种机制允许我们在一个 Agent 中“安装”海量的技能，而不会撑爆上下文窗口。

4 生态对比

为了准确理解 Skills 的定位，我们需要将其与现有的辅助工具进行对比。

4.1 Skill vs Slash Commands

两者都包含预定义的 Prompt 和工作流，但自主性有着本质区别。

特性	Slash Commands (/cmd)	Agent Skills
触发方式	用户手动触发 (User Triggered)	Agent 自主触发 (Agent Triggered)
参数输入	用户需手动填写参数或进行预研	Agent 自主决定何时调用，并自主研究/生成所需参数
动态性	静态流程	动态决策

场景举例：

Slash Command: 用户需要自己查好参数，输入 /search --query "Claude Skills"。
Skill: 用户只需说“帮我研究一下 Claude Skills”，Agent 会自动判断需要搜索，决定使用搜索 Skill，并自动构造查询参数。Skill 将更多的工作负载从用户转移到了 Agent 身上。

4.2 Skills vs. MCPs (Model Context Protocol)

MCP 是连接外部数据和工具的标准协议。Skills 在功能上与 MCP 高度重叠，但在实现复杂度上有所不同。

特性	MCPs	Agent Skills
组成要素	Tools, Resources, Prompts	Markdown 文件, 脚本, 数据 (类似 Resources/Prompts)
实现复杂度	高。需要搭建 MCP Server 基础设施、配置 Client。	低。仅需 Markdown 文件和本地文件夹结构。
上下文加载	全量加载 (当前默认行为)。通常一次性加载所有工具定义。	渐进式加载。仅加载元数据，按需展开细节。

虽然 MCP 在理论上也可以实现“渐进式披露”（例如只告诉 Agent 有哪些 Server，按需加载 Tool 文档），但在目前的 Claude 默认实现中，MCP 依然倾向于全量加载上下文。相比之下，Skills 原生内置了渐进式加载机制，无需额外开发。

第二章: Skillsd的部署与实战操作

1 在Claude 客户端中使用skills

Claude 的桌面版和网页版均原生支持 Skills，且操作方式完全一致。

1.1 启用与配置

进入设置： 点击界面左下角/右上角的头像 -> Settings -> Capabilities。
Skills 面板： 在 Capabilities 页面底部找到 Skills 区域。
默认 Skills： 系统内置了一些由 Anthropic 开发的默认 Skills（初始状态可能为关闭 Off）：
- Skill Creator: 允许通过自然语言 Prompt 让 Claude 自动编写一个新的 Skill（类似于 Vibe Coding）。这是学习官方最佳实践（Best Practices）的捷径。
- MCP Builder / Artifacts Helper: 辅助构建 MCP Server 或 Artifacts 的工具。

1.2 部署自定义 Skill

要上传自己的 Skill，必须遵循严格的打包格式：

格式要求： 必须是一个 .zip 压缩包。
结构要求： 压缩包解压后必须包含一个文件夹，且该文件夹根目录下必须存在合法的 skill.md 文件（包含 YAML Frontmatter）。
操作步骤： 直接将 .zip 文件拖入 Claude 对话框或上传区域。
- 系统反馈：如果格式正确，系统会提示 "Skill uploaded successfully"。

第三章: 实战案例A: 金融建模Cohort Analysis

本案例展示了 Skill 如何将一个复杂的金融分析任务自动化，并保证数据的准确性。

1. 任务背景

输入数据： 一个包含约 20,000 条交易记录、涉及 1,000 名客户的 CSV 文件 (transactions.csv)。
目标： 构建一个动态的群组分析（Cohort Analysis）Excel 模型。

2. Skill执行流程

当用户上传 CSV 并发出指令“构建 Cohort 模型”时：

意图识别： Agent 扫描 CSV 结构，根据 Skill 的 description 识别出 Cohort Analysis Skill 是处理此任务的最佳工具。
渐进式加载： Agent 读取该 Skill 的完整 skill.md，获取建模步骤和逻辑。
代码执行与生成：
- Agent 编写并执行 Python 代码处理数据。
- 生成 Excel 文件，包含原始数据（Raw Data）和模型计算页（Model Tab）。
自动化验证 (关键步骤)：
- 在 Skill 的 scripts/ 文件夹中，包含一个 validation.py 脚本。
- Agent 在生成 Excel 后，会自动运行此验证脚本，检查公式是否存在错误（如 #DIV/0!、引用错误等），确保交付物的可用性。

3. 交付物细节

生成的 Excel 模型具有以下生产级特性：

动态公式 (Formula Based)： 所有的单元格（如留存率、LTV）都是基于公式计算的，而非静态死数。
参数控制表 (Input Assumptions)： 模型顶部设有参数输入区（例如“假设流失率”）。
- 交互演示：用户在 Excel/Google Sheets 中将参数从 20% 改为 5%，整个模型的留存矩阵和 LTV 数据会实时自动更新。
包含指标： Retention Matrix（留存矩阵）、Customer Counts、Transaction Counts、Revenue、LTV（生命周期价值）、CAC Adjusted LTV（获客成本调整后的 LTV）。

这种级别的模型通常需要金融分析师花费数小时手动构建。通过 Skill，Agent 不仅完成了构建，还通过验证脚本保证了零错误率。

第四章: 在Claude Code中继承Skills

对于开发者，在代码环境（Claude Code / Agent SDK）中使用 Skills 更为灵活，且便于版本控制。

1 目录规范结构

在 Claude Code 项目中，Skills 的部署无需压缩为 Zip，直接以文件夹形式存在。

标准路径：
在项目根目录下的 .claude/ (或自定义的 claude/) 文件夹中创建 skills/ 子目录。

Project_Root/
├── .claude/                <-- Claude 配置目录
│   ├── config.json
│   └── skills/             <-- 存放所有 Skill 文件夹
│       ├── cohort-analysis/
│       │   ├── skill.md
│       │   └── scripts/
│       ├── excel-tool/     <-- Anthropic 官方 Excel Skill
│       └── youtube-thumbnails/

2 官方skill资源

Anthropic 提供了一个官方仓库 (document-skills)，包含处理常见文档类型的标准 Skills：

PDF Processing
DOCX / Word Processing
PPTX / PowerPoint
Excel File Handling

第五章: 实战B 高阶自定义 Skill (YouTube 封面生成器)

1. Skill 设计解剖 (youtube-thumbnails/skill.md)

A. 触发条件 (Description)

明确定义何时使用：“当用户要求从头创建封面 (Create from scratch) 或编辑现有封面 (Edit existing) 时使用。”

B. 上下文索引表 (The Context TOC Pattern)

为了避免一次性加载所有素材（导致 Token 爆炸），该 Skill 在 skill.md 顶部维护了一个上下文文件索引表，将资源分为“必读”和“选读”。

资源名称	文件路径	描述/加载逻辑
Design Requirements	docs/design_reqs.md	[必读] 包含所有封面的核心设计原则（如高对比度、面部特写等）。Agent 每次执行任务前必须读取。
Prompting Guidelines	docs/prompt_guide.md	[必读] 针对绘图模型 (Nano Banana/Gemini) 的 Prompt 最佳实践。
Templates	assets/templates.md	[选读] 包含经过验证的高点击率封面模板。仅当 Agent 决定使用“模板模式”而非“从零创作模式”时才加载。
Assets (Icons/Headshots)	../global_assets/	[选读] 甚至可以指向 Skill 文件夹外部的全局资源路径。

原理分析： 这种设计迫使 Agent 先阅读“目录”，然后根据当前策略（是套模板还是原创？）决定是否去读取 templates.md。这就是渐进式披露的终极形态。

2 上下文工程架构

展示了一个名为“个人助理”的系统，其核心在于一套递归式的上下文管理系统。

根索引文件 (claude.md): 位于 .claude/ 或 context/ 根目录。它不包含具体信息，而是作为导航地图，告诉 Agent 系统由 memory/, projects/, tools/ 三个子系统组成。
子目录索引： 当 Agent 进入 projects/ 目录时，会先读取该目录下的 claude.md，其中列出了所有项目的简介。
按需深入：
- Agent: "用户问的是 YouTube 项目。"
- Action: 读取projects/youtube/claude.md。
- Result: 发现 project_overview.md 和 youtube_studio.md，进而读取具体细节。

核心价值： Agent 像浏览文件系统一样浏览上下文，而非将几万字的文档一次性塞入 System Prompt。

3 完整工作流演示

场景： 为当前视频（Claude Skills 教程）生成封面图。

步骤 1：调研与多模态分析

用户提供 research.md，内含竞争对手的 Top 5 视频链接。
Agent 调用 YouTube Analytics MCP 获取数据。
Agent 使用 Bash curl 命令下载竞品封面图。
关键点： Claude 是多模态 (Multimodal) 的。它直接“看”了下载的竞品图片，分析其设计模式（构图、文字占比），并将这些 Insight 存入上下文。

步骤 2：概念生成

Agent 结合竞品分析，提出两个封面概念：
1. Unfair Advantage Angle (点击率导向)
2. Complete System Angle (系统化教学导向)
用户选择方案 2。

步骤 3：调用 Skill 生成图片

Agent 激活 YouTube Thumbnail Skill。
根据 Skill 指引，Agent 决定使用模板，因此加载 templates.md。
Agent 编写绘图 Prompt，并直接在终端执行命令。
- 命令示例：调用 gemini CLI 或相关 Agent，连接到绘图 MCP (被称为 Nano Banana MCP) 进行生成。

步骤 4：结果交付与迭代

生成的图片直接保存到本地。
第一次生成的图片（方案 1）效果一般（亚洲面孔、非本人），但方案 2（Split Screen Before/After）效果很好，只需微调。
Vibe Coding 修复法： 如果 Skill 表现不佳，直接告诉 Agent：“你失败了，原因是 X，期望是 Y。请复盘 Skill 流程并提出修改建议。” Agent 会自我诊断并修改 skill.md。

第六章 skill 的调试与迭代方法论

没有任何一个 Skill 是第一次编写就能完美运行的。创建 Skill 本质上是一种Vibe Coding（直觉编程/交互式编程）的过程。当 Skill 表现不符合预期时，应遵循以下标准调试流程。

1. 故障诊断流程

当 Agent 执行 Skill 失败或输出质量差（例如生成的缩略图只有文字没有图像，或者 Excel 公式错误）时：

明确差异 (Gap Analysis)：
- 向 Agent 展示期望输出 (Expected Output) 。
- 向 Agent 展示实际输出 (Actual Output) 。
- 明确指出：“Skill 失败了，原因是 X。”
根因分析 (Root Cause Analysis)：
- 命令 Agent：“请重新阅读完整的 skill.md 文件。”
- 追问：“请分析为什么当前的指令导致了上述失败？是逻辑漏洞、缺少边界条件，还是 Prompt 描述不清？”
自动修复 (Auto-Fix)：
- 命令 Agent：“根据分析结果，提出具体的修改建议，并直接更新 skill.md 文件。”

实战技巧： 不要手动去修改 Markdown 文件。让构建 Skill 的 Agent (Skill Creator) 自己去修补 Skill。这能形成一个自我进化的闭环。

2. 案例复盘：YouTube 封面生成器的优化

在演示中，Agent 生成的第一版封面（Option 1）效果不佳（面孔错误、构图混乱）。

问题点： docs/prompt_guide.md 中的 Prompting Guidelines 对“人物一致性”和“构图简洁性”的约束不够强。
优化方案： 通过上述流程，更新 skill.md 及其引用的文档，强制 Agent 在生成图片前先检查 assets/headshots/ 中的人物特征，并在 Prompt 中显式加入 Negative Prompts（负面提示词）。

第七章: 总结

1. 为什么选择 Skills？

Skills 并不是要通过复杂的技术取代现有的工具（Tools/MCPs），而是为了解决上下文工程 (Context Engineering) 的核心矛盾。

Token 效率 (Context Efficiency)： 通过渐进式披露 (Progressive Disclosure) ，将 3,000+ Tokens 的工具定义压缩为 ~50 Tokens 的元数据，仅在需要时加载细节。
架构极简 (Simplicity)： 无需维护服务器，只需管理 Markdown 文件。
能力复利 (Compounding Abilities)： Skills 可以调用其他 Skills（如 Excel Skill 调用 Python 脚本），也可以调用底层 API，形成能力的层级叠加。

2. 适用场景建议

适合使用 Skills 的场景：
- 有明确步骤的复杂工作流（如：金融建模、长文档分析）。
- 需要根据上下文动态加载大量参考资料的任务（如：法律条文查询、特定风格的文案写作）。
- 需要人类专家经验（SOP）固化下来的任务。
适合使用原生 Tools/MCP 的场景：
- 原子化的操作（如：查询当前天气、发送 Slack 消息）。
- 即时性强、无状态的操作。