Quartz 4

🔍 搜索

Skill教程

16 min read

Claude Skill 开发教程

目录

  1. 什么是 Skill
  2. 目录结构
  3. SKILL.md 格式
  4. 触发机制
  5. 渐进式加载
  6. 附加资源
  7. 描述字段最佳实践
  8. 创建 Skill 的步骤
  9. 验证清单
  10. 最佳实践
  11. 常见错误
  12. 示例模板

什么是 Skill

Skill 是一种模块化、自包含的扩展包，通过提供专业化知识、工作流程和工具来扩展 Claude 的能力。

Skill 提供的内容

  1. 专业化工作流 - 特定领域的多步骤程序
  2. 工具集成 - 处理特定文件格式或 API 的说明
  3. 领域专业知识 - 公司特定知识、架构、业务逻辑
  4. 打包资源 - 用于复杂和重复任务的脚本、参考、资产

Skill vs 其他扩展方式

类型触发方式用途
SkillClaude 自动根据描述匹配知识引导、工作流程
Command用户主动调用（如 /commit）简化的复杂操作
AgentClaude 生成或用户配置自主处理复杂任务
Hook事件驱动拦截和修改行为

目录结构

最小结构

skill-name/
└── SKILL.md          # 必需

标准结构（推荐）

skill-name/
├── SKILL.md          # 必需：主定义文件
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── examples/         # 可选：示例文件

完整结构

skill-name/
├── SKILL.md          # 必需：主定义文件
├── README.md         # 可选：额外文档
├── scripts/          # 可选：可执行代码
│   ├── validate.sh
│   └── helper.py
├── references/       # 可选：参考文档
│   ├── patterns.md
│   └── api-docs.md
├── examples/         # 可选：示例文件
│   └── example-config.json
└── assets/           # 可选：输出资源
    ├── template.html
    └── logo.png

Plugin 中的位置

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── scripts/
        ├── references/
        └── examples/

SKILL.md 格式

完整模板

---
name: skill-name                    # 必需：技能标识符（kebab-case）
description: This skill should be used when the user asks to "phrase1", "phrase2", "phrase3", or mentions "keyword".
version: 1.0.0                       # 可选：语义化版本
license: MIT                         # 可选：许可证信息
---
 
# Skill 标题
 
简要描述这个技能的用途（1-2 句话）。
 
## Overview
 
更详细地说明这个技能做什么以及为什么有用。
 
## When This Skill Applies
 
描述激活条件（应该在 frontmatter 中已经说明，这里可以展开）。
 
## Core Concepts
 
解释关键概念和背景知识。
 
## How to Use
 
### 步骤 1
 
说明第一步。
 
### 步骤 2
 
说明第二步。
 
## Additional Resources
 
### Reference Files
 
- **`references/patterns.md`** - 详细模式说明
- **`references/api-docs.md`** - API 参考
 
### Examples
 
- **`examples/example.json`** - 使用示例
 
### Scripts
 
- **`scripts/validate.sh`** - 验证脚本
 
## Notes
 
任何额外的提示、注意事项或最佳实践。

Frontmatter 字段说明

字段必需说明
name✅技能标识符，使用 kebab-case（my-skill）
description✅触发条件，决定何时加载此技能
version❌语义化版本号（1.0.0）
license❌许可证引用（MIT）

Markdown 正文要求

  • 使用祈使语气/不定式形式：“To do X, do Y”
  • 避免使用第二人称：“You should do X”
  • 保持简洁、结构化
  • 使用清晰的标题和列表

触发机制

工作流程

┌─────────────────┐
│   Claude 扫描   │
│   skills/ 目录  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 提取 SKILL.md   │
│ 元数据          │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   用户发起查询   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 匹配 description│
│ 中的触发短语    │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 ┌──────┐  ┌──────────┐
 │匹配  │  │ 不匹配   │
 └──┬───┘  └────┬─────┘
    │           │
    ▼           ▼
┌─────────┐  ┌────────┐
│加载完整 │  │ 忽略   │
│技能内容 │  │ 技能   │
└─────────┘  └────────┘

关键：description 字段

description 是触发机制的核心，它告诉 Claude 何时应该使用这个技能。

渐进式加载

三层加载系统

层级内容加载时机大小限制
1元数据 (name + description)始终~100 词
2SKILL.md 正文技能触发时<5,000 词（理想 1,500-2,000）
3附加资源 (references、examples、scripts)Claude 按需判断无限制

设计优势

  • 节省上下文窗口 - 只在需要时加载详细内容
  • 提高响应速度 - 元数据始终可用，快速匹配
  • 灵活的资源管理 - 大型参考文档不必常驻内存

附加资源

scripts/ - 可执行代码

用途：存放需要确定性可靠性或反复重写的代码。

场景：

  • PDF 处理：rotate_pdf.py
  • 数据转换：convert.sh
  • 验证工具：validate.sh

优势：

  • 节省 token
  • 确定性执行
  • 可能无需加载到上下文

references/ - 参考文档

用途：记录 Claude 工作时需要参考的文档。

场景：

  • 数据库架构：finance.md
  • API 文档：api-spec.md
  • 公司政策：policies.md
  • 详细说明：patterns.md、advanced.md

最佳实践：

  • SKILL.md 保持精简（1,500-2,000 词）
  • 详细内容放入 references/
  • 避免信息重复

examples/ - 示例文件

用途：完整可用的代码或配置示例，用户可以直接复制使用。

场景：

  • 配置模板
  • 完整脚本
  • 工作示例代码

assets/ - 资产文件

用途：输出中使用的素材，不加载到上下文。

场景：

  • 模板：HTML/React 模板
  • 图片：logo、图标
  • 字体：自定义字体文件
  • 其他：PPT 模板、示例文档

描述字段最佳实践

格式要求

使用第三人称格式：

# ✅ 正确
description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events.
 
# ❌ 错误 - 不是第三人称
description: Use this skill when creating hooks.
 
# ❌ 错误 - 太模糊
description: Provides guidance for working with hooks.

包含的内容

  • ✅ 具体的触发短语：“create X”, “configure Y”
  • ✅ 关键词：“hook”, “MCP server”
  • ✅ 场景说明：用户可能问的问题样式
  • ❌ 模糊描述：“Provides help”
  • ❌ 第二人称：“You should use this”

好的描述示例

description: This skill should be used when the user asks to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices.
 
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications.

创建 Skill 的步骤

Step 1: 理解使用场景

跳过此步骤仅当已清楚了解使用模式。收集具体示例：

问题示例：

  • “这个技能应该支持什么功能？”
  • “能给我一些使用这个技能的例子吗？”
  • “你可以想象用户会问什么问题来触发这个技能吗？”

目标：明确技能的功能边界

Step 2: 规划可复用内容

分析每个示例，确定需要什么资源：

示例任务所需资源
”旋转这个 PDF”scripts/rotate_pdf.py
”今天有多少用户登录？“references/schema.md
”构建一个待办事项应用”assets/frontend-template/

Step 3: 创建目录结构

mkdir -p skills/my-skill/{references,examples,scripts,assets}
touch skills/my-skill/SKILL.md

注意：只创建实际需要的目录。

Step 4: 编写 SKILL.md

编写要求

  1. 描述字段（frontmatter）：

    • 第三人称：“This skill should be used when…”
    • 具体触发短语
    • 清晰的场景描述

  2. 正文内容：

    • 祈使语气：“Start by… Read the file…”
    • 避免：“You should…” “Claude should…”

  3. 内容组织：

    • 保持精简（1,500-2,000 词）
    • 回答三个问题：
      • 技能目的是什么？
      • 何时使用？（已在描述中）
      • 实际如何使用？

SKILL.md 内容结构

---
name: My Skill
description: This skill should be used when the user asks to "phrase1", "phrase2".
version: 1.0.0
---
 
# My Skill
 
简要描述技能用途。
 
## When This Skill Applies
 
激活条件说明。
 
## How to Use
 
步骤说明...
 
## Additional Resources
 
### References
- `references/detailed.md` - 详细说明

Step 5: 验证和测试

验证清单

  • SKILL.md 文件存在，frontmatter 格式正确
  • frontmatter 中有 name 和 description
  • description 使用第三人称，包含具体触发短语
  • 正文使用祈使语气
  • SKILL.md 保持精简（<5,000 词）
  • 所有引用的文件实际存在
  • 示例文件完整可用
  • 脚本可执行且功能正确

测试方法

# 使用本地插件测试
cc --plugin-dir /path/to/plugin
 
# 提出应该触发技能的问题
# 验证技能正确加载

Step 6: 迭代改进

在使用中发现问题后进行改进：

常见改进方向：

  • 强化 description 中的触发短语
  • 将长内容从 SKILL.md 移到 references/
  • 添加缺失的示例或脚本
  • 澄清模糊的说明
  • 添加边缘情况处理

验证清单

结构检查

  • SKILL.md 文件存在
  • SKILL.md 有有效的 YAML frontmatter
  • frontmatter 包含 name 和 description 字段
  • 引用的文件实际存在
  • 目录结构符合规范

描述质量

  • 使用第三人称 (“This skill should be used when…“)
  • 包含具体触发短语
  • 列出具体场景 (“create X”, “configure Y”)
  • 避免模糊描述

内容质量

  • 正文使用祈使语气/不定式形式
  • SKILL.md 保持精简 (1,500-2,000 词，<5,000 上限)
  • 详细内容移至 references/
  • 示例完整可用
  • 脚本可执行且有文档

渐进式加载

  • 核心概念在 SKILL.md
  • 详细文档在 references/
  • 可运行代码在 examples/
  • 工具脚本在 scripts/
  • SKILL.md 引用了这些资源

功能测试

  • 技能在预期查询时触发
  • 内容对预期任务有帮助
  • 文件间无重复信息
  • references 按需加载

最佳实践

✅ DO（应该做的）

  • 使用第三人称描述：“This skill should be used when…”
  • 包含具体触发短语：“create X”, “configure Y”
  • SKILL.md 保持精简 (1,500-2,000 词)
  • 使用渐进式加载（details → references/）
  • 使用祈使语气
  • 清晰引用支持文件
  • 提供可用的示例
  • 为常用操作创建工具脚本
  • 参考 plugin-dev 的技能作为模板

❌ DON’T（不应该做的）

  • 任何地方使用第二人称 (“You should…“)
  • 触发条件模糊
  • 所有内容堆在 SKILL.md (>3,000 词无 references/)
  • 使用第二人称语气
  • 引用但不使用的资源
  • 包含损坏或不完整的示例
  • 跳过验证步骤
  • description 太短或无具体触发短语

写作风格对比

反面示例正面示例
You should start by readingStart by reading
You need to configureConfigure
You must validateValidate
This helps you use the skillUse the skill to…
Claude should extract fieldsExtract fields

常见错误

错误 1：触发描述太弱

# ❌ Bad
description: Provides guidance for working with hooks.
# 太模糊，无具体触发短语，不是第三人称
 
# ✅ Good
description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events.
# 第三人称，具体短语，明确场景

错误 2：SKILL.md 内容太多

# ❌ Bad
skill-name/
└── SKILL.md     # 8,000 词 - 所有内容在一个文件
# 问题：每次触发都加载大量内容

# ✅ Good
skill-name/
├── SKILL.md     # 1,800 词 - 核心内容
└── references/
    ├── patterns.md        # 2,500 词
    └── advanced.md        # 3,700 词
# 优势：渐进式加载，详细内容按需加载

错误 3：使用第二人称写作

# ❌ Bad
You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.
 
# ✅ Good
Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

错误 4：未引用附加资源

# ❌ Bad
# SKILL.md 核心内容
 
[完全没有提到 references/ 或 examples/ 的存在]
 
# ✅ Good
# SKILL.md 核心内容
 
## Additional Resources
 
### Reference Files
- **`references/patterns.md`** - 详细模式说明
- **`references/advanced.md`** - 高级用法
 
### Examples
- **`examples/script.sh`** - 工作示例

示例模板

最小 Skill 模板

---
name: my-minimal-skill
description: This skill should be used when the user asks to "perform this specific task" or mentions "this keyword".
version: 1.0.0
---
 
# My Minimal Skill
 
简要说明技能用途（1-2 句话）。
 
## How to Use
 
1. 执行步骤一
2. 执行步骤二
3. 完成任务

适用场景：简单知识传递，不需要复杂资源

标准 Skill 模板

my-skill/
├── SKILL.md              # 1,500-2,000 词
├── references/
│   └── detailed-guide.md # 详细文档
└── examples/
    └── working-example.sh # 完整示例

适用场景：大多数插件技能，有详细文档

完整 Skill 模板

my-skill/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

适用场景：复杂领域，需要验证工具

真实示例：Hook Development Skill

---
name: Hooks Development
description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).
version: 0.1.0
---

结构：

  • SKILL.md: 1,651 词（精简）
  • references/: 3 个文件（详细内容）
  • examples/: 3 个工作示例
  • scripts/: 3 个实用工具

学习资源

官方示例

参考 plugin-dev 插件中的技能作为最佳实践：

技能特点
hook-development渐进式加载、工具脚本
agent-developmentAI 辅助创建、引用参考
mcp-integration综合参考文档
plugin-settings真实世界示例
command-development清晰关键概念
plugin-structure良好的组织结构

文档位置

~/.claude/plugins/marketplaces/claude-plugins-official/plugins/plugin-dev/skills/
~/.claude/plugins/marketplaces/claude-plugins-official/plugins/example-plugin/skills/

快速参考

创建 Skill 命令

# 创建最小结构
mkdir -p skills/my-skill
touch skills/my-skill/SKILL.md
 
# 创建标准结构
mkdir -p skills/my-skill/{references,examples,scripts,assets}
touch skills/my-skill/SKILL.md

Frontmatter 模板

---
name: skill-name
description: This skill should be used when the user asks to "phrase1", "phrase2", "phrase3".
version: 1.0.0
---

关键要点总结

  1. description 是核心 - 决定触发
  2. 保持精简 - SKILL.md 1,500-2,000 词
  3. 渐进加载 - 详细内容放 references/
  4. 第三人称 - “This skill should be used…”
  5. 祈使语气 - “Start by…” 而非 “You should…”

最后更新：2026-01-30

Graph View