Skills 架构设计与核心概念

深入理解 Skills 的设计理念，掌握创建高质量 Skills 的关键原则

本章概览

Skills 的目录结构和文件组织
SKILL.md 的规范格式
渐进式加载（Progressive Disclosure）设计模式
自由度控制原则
核心设计模式与最佳实践

1. Skills 是什么

1.1 核心定义

通俗比喻：如果把 Claude 比作一个万能工匠，那么 Skills 就是他的"专业工具箱"。每个 Skill 包含特定任务所需的工具、说明书和材料。

Skills = 指令 + 脚本 + 参考资料 + 素材资源

官方定义：

Skills 是由指令、脚本和资源组成的文件夹，Claude 可以动态加载它们以提升在特定任务上的表现。Skills 教会 Claude 如何以可重复的方式完成特定任务。

1.2 Skills 提供什么

能力	说明	示例
专业工作流	特定领域的多步骤流程	文档审阅、PDF 表单填写
工具集成	与特定文件格式或 API 的交互方式	OOXML 操作、MCP 服务器开发
领域专识	公司特定知识、业务逻辑	品牌规范、内部沟通模板
捆绑资源	复杂和重复任务所需的脚本和素材	HTML 模板、Python 脚本、字体文件

2. 目录结构

2.1 标准结构

每个 Skill 是一个自包含的文件夹：

skill-name/
├── SKILL.md              # [必需] 核心指令文件
├── scripts/              # [可选] 可执行脚本
│   ├── rotate_pdf.py
│   └── validate.py
├── references/           # [可选] 参考文档
│   ├── api_docs.md
│   └── schema.md
└── assets/               # [可选] 模板和素材
    ├── template.pptx
    ├── logo.png
    └── fonts/

2.2 各目录用途

SKILL.md（必需）

Skill 的核心文件，包含：

YAML 前置元数据（frontmatter）
Markdown 格式的详细指令

markdown

---
name: my-skill
description: 技能描述，说明何时使用此 Skill
---

# 技能标题

[详细指令内容...]

scripts/（可选）

存放可执行代码，适用于：

需要确定性可靠性的任务
反复重写相同代码的场景

示例：PDF 旋转脚本

python

# scripts/rotate_pdf.py
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, degrees):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    for page in reader.pages:
        page.rotate(degrees)
        writer.add_page(page)
    with open(output_path, 'wb') as f:
        writer.write(f)

优势：

节省 Token（执行时无需加载到上下文）
确定性输出
可独立测试和维护

references/（可选）

存放 Claude 在工作时需要参考的文档：

数据库 Schema
API 文档
领域知识
公司政策

最佳实践：

如果文件超过 10k 词，在 SKILL.md 中提供 grep 搜索模式
信息只在一处存在（SKILL.md 或 references，不要重复）
保持 SKILL.md 精简，详细信息放入 references

assets/（可选）

不需要加载到上下文，但用于输出的文件：

模板文件（PPT、Word、HTML）
图片和图标
字体文件
样板代码

3. SKILL.md 规范

3.1 前置元数据（Frontmatter）

yaml

---
name: skill-name        # [必需] 技能标识符（小写，用连字符）
description: ...        # [必需] 触发条件和功能描述
license: ...            # [可选] 许可证信息
---

关键点：description 是触发机制的核心

Claude 通过 description 判断何时使用该 Skill，因此需要：

清晰说明 Skill 的功能
明确列出触发条件
包含相关关键词

优秀示例：

yaml

description: "Comprehensive document creation, editing, and analysis
with support for tracked changes, comments, formatting preservation,
and text extraction. When Claude needs to work with professional
documents (.docx files) for: (1) Creating new documents,
(2) Modifying or editing content, (3) Working with tracked changes,
(4) Adding comments, or any other document tasks"

3.2 主体内容

使用标准 Markdown 格式，包含：

markdown

# 技能名称

## 概述
简要说明技能的用途和范围

## 工作流程
### 步骤 1: ...
### 步骤 2: ...

## 示例
[代码示例和使用场景]

## 注意事项
[重要的限制和警告]

3.3 不应包含的内容

Skill 文件夹中不要创建：

README.md（技能说明已在 SKILL.md 中）
INSTALLATION_GUIDE.md
CHANGELOG.md
其他辅助文档

Skill 是给 AI Agent 使用的，不是给人类阅读的文档。

4. 渐进式加载设计

4.1 三级加载系统

mermaid

graph TB
    subgraph Level1["Level 1: 元数据"]
        Meta["name + description<br>~100 词<br><b>始终在上下文</b>"]
    end

    subgraph Level2["Level 2: SKILL.md 主体"]
        Body["详细指令<br><5k 词<br><b>触发后加载</b>"]
    end

    subgraph Level3["Level 3: 捆绑资源"]
        Scripts["scripts/"]
        Refs["references/"]
        Assets["assets/"]
    end

    User[用户请求] -->|匹配 description| Meta
    Meta -->|触发| Body
    Body -->|按需| Scripts
    Body -->|按需| Refs
    Body -->|按需| Assets

    style Meta fill:#e1f5fe
    style Body fill:#fff3e0
    style Level3 fill:#f3e5f5

4.2 设计原则

核心原则：上下文窗口是公共资源

上下文预算 = 系统提示 + 对话历史 + Skills 元数据 + 用户请求

默认假设：Claude 已经很聪明了

只添加 Claude 不知道的内容
每段信息都要问："这值得占用 Token 吗？"
简洁示例优于冗长解释

4.3 实践模式

模式 1：高层指南 + 分离的参考文档

markdown

# PDF 处理

## 快速开始
用 pdfplumber 提取文本：
[简短代码示例]

## 高级功能
- **表单填写**: 见 [FORMS.md](FORMS.md)
- **API 参考**: 见 [REFERENCE.md](REFERENCE.md)
- **示例集合**: 见 [EXAMPLES.md](EXAMPLES.md)

Claude 仅在需要时加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

模式 2：按领域组织

bigquery-skill/
├── SKILL.md (总览和导航)
└── reference/
    ├── finance.md    (营收、账单指标)
    ├── sales.md      (商机、管道)
    ├── product.md    (API 用量、功能)
    └── marketing.md  (活动、归因)

当用户询问销售指标时，Claude 只读取 sales.md。

模式 3：按框架/变体组织

cloud-deploy/
├── SKILL.md (工作流 + 提供商选择)
└── references/
    ├── aws.md    (AWS 部署模式)
    ├── gcp.md    (GCP 部署模式)
    └── azure.md  (Azure 部署模式)

用户选择 AWS 时，Claude 只读取 aws.md。

5. 自由度控制原则

5.1 什么是自由度

通俗比喻：想象 Claude 在探索一条路径：

窄桥（悬崖两侧）→ 需要精确的护栏（低自由度）
开阔原野 → 可以选择多条路线（高自由度）

5.2 三个级别

自由度	适用场景	实现方式
高	多种方法都可行、决策依赖上下文	文本指令、启发式规则
中	有首选模式、允许一定变化	伪代码、带参数的脚本
低	操作易出错、一致性关键、必须按顺序执行	具体脚本、少量参数

5.3 示例对比

高自由度：前端设计

markdown

## 设计思考

在编码前，理解上下文并确定一个**大胆的**美学方向：
- **目的**：这个界面解决什么问题？谁使用它？
- **调性**：选择一个极端：极简主义、复古未来、奢华精致...
- **差异化**：什么让它令人难忘？

**关键**：选择清晰的概念方向，精准执行。

中自由度：MCP 服务器开发

markdown

## 工具实现

对于每个工具：

**输入 Schema:**
- 使用 Zod (TypeScript) 或 Pydantic (Python)
- 包含约束和清晰描述
- 在字段描述中添加示例

**输出 Schema:**
- 尽可能定义 `outputSchema`
- 在工具响应中使用 `structuredContent`

低自由度：OOXML 编辑

markdown

## 工作流程

1. **解包文档**:
   `python ooxml/scripts/unpack.py <office_file> <output_dir>`

2. **编辑 XML 文件**

3. **[关键] 立即验证**:
   `python ooxml/scripts/validate.py <dir> --original <file>`

4. **打包文档**:
   `python ooxml/scripts/pack.py <input_dir> <office_file>`

6. 核心设计模式

6.1 工作流模式

适用于需要多步骤、有条件分支的任务。

markdown

## 工作流决策树

用户任务 → 是静态 HTML 吗？
    ├─ 是 → 直接读取 HTML 文件识别选择器
    │         ├─ 成功 → 使用选择器编写 Playwright 脚本
    │         └─ 失败 → 按动态应用处理
    │
    └─ 否 → 服务器已运行？
        ├─ 否 → 运行: python scripts/with_server.py --help
        │        使用 helper + 编写 Playwright 脚本
        │
        └─ 是 → 侦察后行动：
            1. 导航并等待 networkidle
            2. 截图或检查 DOM
            3. 从渲染状态识别选择器
            4. 使用发现的选择器执行操作

6.2 模板模式

适用于需要一致输出格式的任务。

markdown

## 输出格式

输出：
1. **算法哲学** - Markdown 解释生成美学
2. **单一 HTML Artifact** - 自包含的交互式生成艺术

HTML artifact 包含所有内容：p5.js（CDN）、算法、参数控制、UI

6.3 检查清单模式

适用于容易出错、需要验证的任务。

markdown

## 公式验证清单

### 必要验证
- [ ] **测试 2-3 个样本引用**: 构建完整模型前验证正确性
- [ ] **列映射**: 确认 Excel 列匹配（如 64 列 = BL，不是 BK）
- [ ] **行偏移**: 记住 Excel 行从 1 开始（DataFrame 行 5 = Excel 行 6）

### 常见陷阱
- [ ] **NaN 处理**: 用 `pd.notna()` 检查空值
- [ ] **除零错误**: 在公式中使用 `/` 前检查分母
- [ ] **引用错误**: 验证所有单元格引用指向预期单元格

6.4 示例模式

通过具体示例展示期望行为。

markdown

## 哲学示例

**"有机湍流"**
哲学: 被自然法则约束的混沌，秩序从无序中涌现。
算法表达: 由分层 Perlin 噪声驱动的流场。数千粒子跟随向量力，
它们的轨迹累积成有机密度图。多个噪声八度创造湍流区域和平静区域...

**"量子谐波"**
哲学: 离散实体表现出波浪般的干涉模式。
算法表达: 粒子在网格上初始化，每个携带一个相位值...

7. 元数据触发机制

7.1 触发条件设计

description 中应包含：

yaml

description: |
  [功能描述] + [触发条件]

  示例格式:
  "Comprehensive [功能] for [用途]. Use when Claude needs to
  [场景 1], [场景 2], or [场景 3]."

7.2 关键词策略

确保覆盖用户可能使用的各种表达方式：

yaml

# pdf skill 的描述
description: "Comprehensive PDF manipulation toolkit for extracting
text and tables, creating new PDFs, merging/splitting documents,
and handling forms. When Claude needs to fill in a PDF form or
programmatically process, generate, or analyze PDF documents at scale."

涵盖关键词：

PDF, 表单, 文档
提取, 合并, 拆分
填写, 处理, 生成, 分析

8. 本章小结

Skills 架构的核心要点：

原则	要点
结构	SKILL.md 必需，scripts/references/assets 可选
加载	三级渐进式加载，节省上下文
触发	description 是核心，清晰列出功能和触发条件
自由度	根据任务脆弱性选择合适的指令精确度
精简	默认 Claude 很聪明，只添加必要信息

掌握这些原则后，你就能创建高效、可复用的 Skills 了。

上一章：项目简介

下一章：创意设计类 Skills

Skills 架构设计与核心概念 ​

本章概览 ​

1. Skills 是什么 ​

1.1 核心定义 ​

1.2 Skills 提供什么 ​

2. 目录结构 ​

2.1 标准结构 ​

2.2 各目录用途 ​

SKILL.md（必需） ​

scripts/（可选） ​

references/（可选） ​

assets/（可选） ​

3. SKILL.md 规范 ​

3.1 前置元数据（Frontmatter） ​

3.2 主体内容 ​

3.3 不应包含的内容 ​

4. 渐进式加载设计 ​

4.1 三级加载系统 ​

4.2 设计原则 ​

4.3 实践模式 ​

模式 1：高层指南 + 分离的参考文档 ​

模式 2：按领域组织 ​

模式 3：按框架/变体组织 ​

5. 自由度控制原则 ​

5.1 什么是自由度 ​

5.2 三个级别 ​

5.3 示例对比 ​

高自由度：前端设计 ​

中自由度：MCP 服务器开发 ​

低自由度：OOXML 编辑 ​

6. 核心设计模式 ​

6.1 工作流模式 ​

6.2 模板模式 ​

6.3 检查清单模式 ​

6.4 示例模式 ​

7. 元数据触发机制 ​

7.1 触发条件设计 ​

7.2 关键词策略 ​

8. 本章小结 ​

Skills 架构设计与核心概念

本章概览

1. Skills 是什么

1.1 核心定义

1.2 Skills 提供什么

2. 目录结构

2.1 标准结构

2.2 各目录用途

SKILL.md（必需）

scripts/（可选）

references/（可选）

assets/（可选）

3. SKILL.md 规范

3.1 前置元数据（Frontmatter）

3.2 主体内容

3.3 不应包含的内容

4. 渐进式加载设计

4.1 三级加载系统

4.2 设计原则

4.3 实践模式

模式 1：高层指南 + 分离的参考文档

模式 2：按领域组织

模式 3：按框架/变体组织

5. 自由度控制原则

5.1 什么是自由度

5.2 三个级别

5.3 示例对比

高自由度：前端设计

中自由度：MCP 服务器开发

低自由度：OOXML 编辑

6. 核心设计模式

6.1 工作流模式

6.2 模板模式

6.3 检查清单模式

6.4 示例模式

7. 元数据触发机制

7.1 触发条件设计

7.2 关键词策略

8. 本章小结