Skill Creator Skill 详解

创建高质量 Skills 的元指南

基本信息

属性	值
名称	skill-creator
类别	工作流程
输出格式	.skill 包
许可证	Apache 2.0

name: skill-creator
description: Guide for creating effective skills. This skill should be
used when users want to create a new skill (or update an existing skill)
that extends Claude's capabilities with specialized knowledge, workflows,
or tool integrations.

---

1. 什么是 Skills

1.1 核心概念

通俗比喻：Skills 就像是为 Claude 量身定制的"培训手册"——它们将通用 AI 转变为特定领域的专家。

1.2 Skills 提供什么

类型	说明
专业工作流	特定领域的多步骤流程
工具集成	处理特定文件格式或 API 的指令
领域专识	公司特定知识、schema、业务逻辑
捆绑资源	脚本、参考文档、素材

---

2. 核心原则

2.1 简洁至上

**上下文窗口是公共资源**

Skills 与其他内容共享上下文窗口：
- 系统提示
- 对话历史
- 其他 Skills 的元数据
- 用户请求

**默认假设：Claude 已经非常聪明**
- 只添加 Claude 不知道的信息
- 质疑每条信息："Claude 真的需要这个解释吗？"
- 优先使用简洁的示例而非冗长的解释

2.2 设置适当的自由度

匹配任务的脆弱性和变化性：

**高自由度**（文本指令）：
- 多种方法都有效时
- 决策依赖上下文时
- 使用启发式规则时

**中等自由度**（伪代码或带参数的脚本）：
- 存在首选模式时
- 可接受一些变化时
- 配置影响行为时

**低自由度**（特定脚本，少参数）：
- 操作脆弱易出错时
- 一致性至关重要时
- 必须遵循特定序列时

---

3. Skill 结构

3.1 目录结构

skill-name/
├── SKILL.md (必需)
│   ├── YAML frontmatter 元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown 指令 (必需)
└── 捆绑资源 (可选)
    ├── scripts/          - 可执行代码
    ├── references/       - 按需加载的文档
    └── assets/           - 输出中使用的文件

3.2 SKILL.md 结构

---
name: my-skill
description: 清晰描述 skill 做什么以及何时使用。这是触发机制，
必须全面描述使用场景。
---

# Skill 标题

## 概述
[简要介绍]

## 工作流程
[详细步骤]

## 参考资源
[链接到 references/ 中的文件]

3.3 捆绑资源

scripts/

**何时包含**：
- 相同代码被反复重写时
- 需要确定性可靠性时

**示例**：scripts/rotate_pdf.py

**优点**：
- Token 高效
- 确定性
- 可不加载到上下文直接执行

references/

**何时包含**：
- Claude 工作时需要参考的文档

**示例**：
- references/finance.md（金融 schema）
- references/api_docs.md（API 文档）
- references/policies.md（公司政策）

**最佳实践**：
- 大文件（>10k 词）包含 grep 搜索模式
- 信息只放在一处（SKILL.md 或 references，不要重复）

assets/

**何时包含**：
- Skill 需要在输出中使用的文件

**示例**：
- assets/logo.png（品牌素材）
- assets/slides.pptx（PPT 模板）
- assets/frontend-template/（HTML/React 样板）

3.4 不要包含的内容

**不要创建这些文件**：
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md

Skill 只应包含 AI agent 完成工作所需的信息
不需要创建过程、设置程序、用户文档等辅助内容

---

4. 渐进式加载原则

4.1 三级加载系统

Level 1: 元数据 (name + description)  ─ 始终在上下文 (~100词)
    │
Level 2: SKILL.md 主体 ─────────────── 触发后加载 (<5k词)
    │
Level 3: 捆绑资源 ──────────────────── 按需加载 (无限)

4.2 渐进式加载模式

模式1：高层指南 + 参考文件

# PDF 处理

## 快速开始
[代码示例]

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

模式2：按领域组织

bigquery-skill/
├── SKILL.md (概述和导航)
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

模式3：条件详情

# DOCX 处理

## 创建文档
使用 docx-js。见 [DOCX-JS.md](DOCX-JS.md)。

## 编辑文档
简单编辑直接修改 XML。

**修订跟踪**：见 [REDLINING.md](REDLINING.md)
**OOXML 详情**：见 [OOXML.md](OOXML.md)

---

5. 创建流程

5.1 六步流程

graph LR
    A[1. 理解用例] --> B[2. 规划内容]
    B --> C[3. 初始化]
    C --> D[4. 编辑 Skill]
    D --> E[5. 打包]
    E --> F[6. 迭代]

5.2 步骤详解

步骤1：用具体示例理解 Skill

提问：
- "这个 Skill 应该支持什么功能？"
- "能给一些使用示例吗？"
- "用户会说什么来触发这个 Skill？"

当对 Skill 应支持的功能有清晰认识时，完成此步骤

步骤2：规划可复用内容

分析每个示例：
1. 考虑如何从零执行
2. 识别重复执行时有帮助的脚本、参考、素材

示例分析：
- 旋转 PDF → 需要 scripts/rotate_pdf.py
- 构建前端 → 需要 assets/hello-world/ 模板
- 查询 BigQuery → 需要 references/schema.md

步骤3：初始化 Skill

scripts/init_skill.py <skill-name> --path <output-directory>

脚本会：

• 创建 skill 目录
• 生成带 frontmatter 的 SKILL.md 模板
• 创建示例资源目录

步骤4：编辑 Skill

**Frontmatter**：
- name：Skill 名称
- description：主要触发机制，必须清晰全面

**正文**：
- 使用 Skill 及其资源的指令
- 使用祈使语气

**记住**：你在为另一个 Claude 实例创建 Skill
包含对 Claude 有益且非显而易见的信息

步骤5：打包 Skill

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

# 可选：指定输出目录
scripts/package_skill.py <path/to/skill-folder> ./dist

脚本会：

1. 验证 Skill（frontmatter、命名、结构等）
2. 如果验证通过，创建 .skill 文件

步骤6：迭代

1. 在实际任务中使用 Skill
2. 注意困难或低效之处
3. 识别需要更新的内容
4. 实施更改并再次测试

---

6. 使用示例

6.1 触发方式

"帮我创建一个处理 CSV 文件的 Skill"
"create a skill for our internal API"
"update the existing pdf skill"

---

7. 本节小结

要点	说明
简洁至上	只添加必要信息
自由度匹配	根据任务脆弱性设置
渐进式加载	三级加载节省上下文
六步流程	理解→规划→初始化→编辑→打包→迭代
Description 关键	是主要触发机制

---

返回：Skills 目录