Claude Skills 编写最佳实践指南

Published

第一部分：核心理念 #

1.1 什么是 Skill？ #

Skill 是模块化、自包含的知识包，用于扩展 Claude 的能力。把它想象成针对特定领域的"入职指南"——将通用 Claude 转变为具备专业知识的领域专家。

Skill 提供的核心价值：

1.2 黄金法则：Claude 本身就很聪明 #

默认假设：Claude 已经非常智能。

每一段内容都要经受这个拷问：

💡 核心原则：简洁的示例 > 冗长的解释

1.3 上下文窗口是公共资源 #

Skill 与以下内容共享上下文窗口：

每个 token 都有成本。节约使用。

第二部分：自由度设计 #

根据任务的脆弱性和变化性，匹配不同的指令精确度：

自由度形式适用场景
高文本指南多种方案都可行、决策依赖上下文、只需启发式引导
中伪代码/带参数脚本存在首选模式、允许一定变化、配置影响行为
低精确脚本+少量参数操作脆弱易错、一致性至关重要、必须严格遵循顺序

🌉 形象比喻：悬崖边的窄桥需要精确的护栏（低自由度），开阔的原野允许多条路线（高自由度）。

第三部分：Skill 结构规范 #

3.1 目录结构 #

skill-name/
├── SKILL.md              # [必需] 核心文档
├── scripts/              # [可选] 可执行脚本
├── references/           # [可选] 参考文档（按需加载）
└── assets/               # [可选] 输出资源（模板、图标、字体）

3.2 SKILL.md 文件结构 #

---
name: skill-name
description: "清晰描述功能 + 触发场景"
---

# 技能标题

## 核心内容

3.3 Frontmatter 编写要点 #

name 字段 #

description 字段 ⭐ 关键 #

这是触发技能的主要机制。必须包含：

  1. 功能描述：技能做什么
  2. 触发场景：何时使用（用编号列举）

优秀示例：

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"

⚠️ 关键提醒：Body 中写"何时使用此技能"是无效的——因为 body 只在技能触发后才加载！所有触发信息必须放在 description 中。

第四部分：渐进式披露设计 #

4.1 三层加载系统 #

层级内容加载时机建议大小
L1元数据（name + description）始终在上下文中~100 词
L2SKILL.md body技能触发时<500 行
L3捆绑资源按需加载无限制*

*脚本可不加载到上下文直接执行

4.2 渐进式披露模式 #

模式一：高层指南 + 引用 #

# PDF 处理

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

## 高级功能
- **表单填充**：参见 [FORMS.md](FORMS.md)
- **API 参考**：参见 [REFERENCE.md](REFERENCE.md)

模式二：按领域组织 #

bigquery-skill/
├── SKILL.md (概览 + 导航)
└── references/
    ├── finance.md    # 财务指标
    ├── sales.md      # 销售数据
    └── product.md    # 产品用量

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

模式三：条件详情 #

## 编辑文档

简单编辑直接修改 XML。

**追踪修改**：参见 [REDLINING.md](REDLINING.md)
**OOXML 详情**：参见 [OOXML.md](OOXML.md)

4.3 关键原则 #

第五部分：三类捆绑资源 #

5.1 Scripts（脚本） #

用途：确定性执行 + 反复重写的代码

scripts/
├── unpack.py       # 解包文档
├── pack.py         # 打包文档
└── validate.py     # 验证输出

何时使用：

最佳实践：

5.2 References（参考文档） #

用途：按需加载的知识库

references/
├── schema.md       # 数据库模式
├── api_docs.md     # API 文档
└── policies.md     # 公司政策

何时使用：

最佳实践：

5.3 Assets（资产） #

用途：不读入上下文，用于最终输出

assets/
├── logo.png           # 品牌资源
├── template.pptx      # PPT 模板
└── frontend-template/ # 前端脚手架

何时使用：

第六部分：编写工艺 #

6.1 写作风格 #

始终使用祈使句/命令式：

✅ 正确：

Extract text with pdfplumber.
Use Arial as the default font.

❌ 错误：

You should extract text with pdfplumber.
The default font should be Arial.

6.2 快速参考表格 #

使用表格快速传达任务-工具映射：

| 任务 | 方法 |
|------|------|
| 读取/分析内容 | `pandoc` 或解包查看 XML |
| 创建新文档 | 使用 `docx-js` |
| 编辑现有文档 | 解包 → 编辑 XML → 重新打包 |

6.3 代码示例原则 #

简洁 + 可直接使用：

# ✅ 好的示例
from pypdf import PdfReader
reader = PdfReader("document.pdf")
text = "".join(page.extract_text() for page in reader.pages)

# ❌ 不好的示例（过度注释）
# Import the PdfReader class from the pypdf library
from pypdf import PdfReader  # We need this to read PDFs
# Create a reader object for our PDF file
reader = PdfReader("document.pdf")  # This opens the PDF

6.4 关键规则/陷阱警示 #

使用醒目格式标注关键规则：

### Critical Rules for docx-js

- **Set page size explicitly** - docx-js defaults to A4
- **Never use `\n`** - use separate Paragraph elements
- **Never use unicode bullets** - use `LevelFormat.BULLET`
- **PageBreak must be in Paragraph** - standalone creates invalid XML

6.5 工作流文档 #

顺序工作流 #

填充 PDF 表单步骤：

1. 分析表单 (运行 analyze_form.py)
2. 创建字段映射 (编辑 fields.json)
3. 验证映射 (运行 validate_fields.py)
4. 填充表单 (运行 fill_form.py)
5. 验证输出 (运行 verify_output.py)

条件工作流 #

1. 确定修改类型：
   **创建新内容？** → 遵循下方"创建工作流"
   **编辑现有内容？** → 遵循下方"编辑工作流"

2. 创建工作流：[步骤]
3. 编辑工作流：[步骤]

第七部分：输出模式 #

7.1 模板模式 #

严格要求时：

## 报告结构

必须使用此精确模板结构：

# [分析标题]

## 执行摘要
[关键发现的一段概述]

## 主要发现
- 发现 1 及支撑数据
- 发现 2 及支撑数据

## 建议
1. 具体可行建议
2. 具体可行建议

灵活指导时：

## 报告结构

这是合理的默认格式，但请根据判断调整：

# [分析标题]

## 执行摘要
[概述]

## 主要发现
[根据发现调整章节]

根据具体分析类型按需调整。

7.2 示例模式 #

当输出质量依赖于示例时，提供输入/输出对：

## 提交信息格式

按以下示例生成提交信息：

**示例 1：**
输入：Added user authentication with JWT tokens
输出：

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware


**示例 2：**
输入：Fixed bug where dates displayed incorrectly
输出：

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation


遵循此风格：type(scope): 简要描述，然后详细解释。

第八部分：实战案例分析 #

8.1 案例一：docx 技能（文档处理） #

亮点：

结构：

docx/
├── SKILL.md          # 主文档（含 XML 参考）
└── scripts/
    ├── unpack.py     # 解包 DOCX
    ├── pack.py       # 打包 DOCX
    ├── comment.py    # 添加批注
    └── accept_changes.py  # 接受修订

8.2 案例二：pdf 技能（渐进式披露） #

亮点：

结构：

pdf/
├── SKILL.md          # 快速参考（~300 行）
├── FORMS.md          # 表单填充专题
├── REFERENCE.md      # API 详细参考
└── scripts/          # 辅助脚本

8.3 案例三：xlsx 技能（领域规范） #

亮点：

技巧：

## CRITICAL: Use Formulas, Not Hardcoded Values

### ❌ WRONG - Hardcoding Calculated Values
sheet['B10'] = total  # Hardcodes 5000

### ✅ CORRECT - Using Excel Formulas
sheet['B10'] = '=SUM(B2:B9)'

8.4 案例四：frontend-design 技能（创意领域） #

亮点：

适用于创意/主观任务的高自由度风格。

第九部分：不该包含的内容 #

Skill 只应包含 AI agent 完成工作所需的核心文件。

❌ 不要创建：

这些只会增加混乱。Skill 不是给人类读的项目文档。

第十部分：创建流程 #

步骤 1：理解具体示例 #

关键问题：
- "这个技能应支持什么功能？"
- "给一些使用示例？"
- "用户会说什么来触发这个技能？"

步骤 2：规划可复用内容 #

分析每个示例：

  1. 如何从头执行这个示例
  2. 重复执行时哪些脚本/引用/资产有帮助

步骤 3：初始化技能 #

scripts/init_skill.py  --path

步骤 4：编辑技能 #

  1. 先实现可复用资源（scripts/references/assets）
  2. 测试脚本确保无 bug
  3. 更新 SKILL.md

步骤 5：打包技能 #

scripts/package_skill.py <path/to/skill-folder>

自动验证 + 打包为 .skill 文件。

步骤 6：迭代 #

在真实任务上测试 → 发现问题 → 改进 → 再测试

第十一部分：质量检查清单 #

Frontmatter 检查 #

SKILL.md Body 检查 #

资源文件检查 #

整体检查 #

附录：常见反模式 #

反模式问题正确做法
过度注释的代码浪费 token代码自解释，关键点简注
SKILL.md 中写"何时使用"不会被读到放入 description
信息重复在多处上下文浪费单一真相来源
深层嵌套引用难以发现一层引用直接从 SKILL.md 链接
缺少具体示例Claude 难以理解预期提供输入/输出对
高自由度用于脆弱任务输出不稳定降低自由度、提供脚本
包含项目管理文件与任务无关只保留核心文件

记住：最好的 Skill 是让 Claude 从通用助手变成领域专家的最短路径。每个 token 都应该为此目标服务。