17.2 编写高质量的SKILL.md文件

第 17 章 · 开发一个技能 · 第5部分：技能 Skills

概述#

SKILL.md文件是Skill的核心，它告诉Claude这个Skill的功能、使用时机以及如何执行任务。编写高质量的SKILL.md文件是一门艺术，需要平衡简洁性和完整性。本节将教你如何编写能够被Claude有效理解和使用的SKILL.md文件。

高质量的SKILL.md文件应该像一本清晰的操作手册，让Claude能够快速找到所需信息并准确执行任务。

YAML Frontmatter规范#

必需字段#

SKILL.md文件必须以YAML frontmatter开头，包含以下必需字段：

markdown
复制
---
name: my-skill-name
description: 详细描述Skill的功能和使用时机。当用户遇到X、Y、Z情况时使用此Skill。
---

# Skill标题

Skill的具体内容...

字段详解：

  • name: Skill的唯一标识符

    • 只允许小写字母、数字和连字符
    • 长度限制：1-64个字符
    • 建议使用描述性名称，如 code-reviewer、data-analyzer

  • description: Skill的功能描述和触发条件

    • 长度：最多1024个字符
    • 应该包含：Skill做什么 + 何时使用
    • 这是Claude判断是否使用此Skill的关键依据

可选字段#

markdown
复制
---
name: advanced-skill
description: 处理复杂数据分析任务
version: 1.0.0
author: Your Name
license: MIT
model: claude-sonnet-4-5-20250929
allowed-tools: Read,Write,Bash(git:*)
---

可选字段说明：

  • version: Skill版本号
  • author: 作者信息
  • license: 开源许可证
  • model: 指定使用的Claude模型
  • allowed-tools: 限制Skill可使用的工具

指令编写原则#

1. 结构化组织#

将指令按照逻辑层次组织，使Claude能够快速定位信息：

markdown
复制
# 数据分析助手

## 概述
简要说明这个Skill的整体功能

## 使用场景
- 场景1：描述和示例
- 场景2：描述和示例

## 执行步骤
1. 第一步：具体操作
2. 第二步：具体操作

## 注意事项
重要的提醒和限制条件

## 示例
实际使用案例

2. 使用清晰的语言#

  • 避免模糊表述，使用具体明确的指令
  • 使用主动语态，让指令更加直接
  • 提供上下文信息，帮助Claude做出决策

不好的示例：

bash
复制
处理数据时要注意一些事情。

好的示例：

bash
复制
处理CSV文件时：
- 检查文件编码，确保是UTF-8
- 验证列标题是否正确
- 处理缺失值，使用平均值填充

3. 条件触发设置#

通过描述字段精确控制Skill的触发时机：

markdown
复制
---
name: excel-processor
description: 处理Excel文件和数据分析。当用户上传.xlsx文件、提到数据透视表、或需要生成图表时使用此Skill。
---

# Excel处理助手

## 触发条件
- 用户提到Excel、Spreadsheet、.xlsx等关键词
- 涉及数据分析、图表生成的任务
- 需要处理表格数据的场景

引用外部文件#

基本引用语法#

在SKILL.md中使用相对路径引用其他文件：

markdown
复制
# 数据处理Skill

## 基本用法
参考 [数据格式说明](references/data-formats.md) 了解支持的数据类型。

## 高级功能
查看 [API文档](references/api-reference.md) 获取完整功能列表。

## 故障排除
遇到问题时，请查阅 [故障排除指南](references/troubleshooting.md)。

引用时机选择#

  • 何时使用引用：

    • 内容过长会影响加载速度
    • 详细信息只有在特定情况下才需要
    • 避免核心指令被冗长内容淹没

  • 何时保留在主文件：

    • 核心使用步骤
    • 重要的安全提醒
    • 经常使用的信息

渐进式披露策略#

markdown
复制
---
name: database-manager
description: 管理数据库操作，包括查询、迁移和优化
---

# 数据库管理助手

## 快速开始
基本查询操作...

## 高级功能
复杂操作请参考 [高级用法指南](references/advanced-usage.md)

## 数据库迁移
迁移步骤请查看 [迁移指南](references/migrations.md)

条件触发和上下文感知#

基于任务类型的触发#

markdown
复制
## 适用场景

### 数据导入
当用户需要将数据导入系统时：
1. 验证数据格式
2. 检查数据完整性
3. 执行导入操作

### 报表生成
当用户请求生成报表时：
1. 确定报表类型
2. 收集必要数据
3. 生成并格式化报表

基于用户意图的触发#

markdown
复制
## 意图识别

如果用户说：
- "帮我分析这个数据" → 执行数据分析流程
- "创建一份报告" → 生成报告流程
- "优化这个查询" → 性能优化流程

Token优化技巧#

1. 精简表达#

使用简洁的语言表达复杂概念：

冗长版本：

bash
复制
当用户要求进行数据可视化的时候，你应该首先理解用户想要展示什么样的数据，然后选择合适的图表类型，接着准备数据，最后生成可视化结果。

优化版本：

bash
复制
数据可视化流程：
1. 分析用户需求和数据特征
2. 选择图表类型（柱状图、折线图、饼图等）
3. 准备和清洗数据
4. 生成可视化图表

2. 标准化表述#

使用一致的格式和术语：

markdown
复制
## 操作清单

✅ **数据验证**
- 检查文件格式
- 验证数据类型
- 处理异常值

✅ **处理执行**
- 应用指定操作
- 记录处理结果
- 生成输出文件

✅ **结果验证**
- 检查输出完整性
- 验证结果准确性
- 提供处理摘要

3. 条件加载#

只在需要时加载详细信息：

markdown
复制
## 高级配置

如需自定义设置，请查看 [配置选项](references/configuration.md)。

## 故障排除

常见问题请参考 [FAQ](references/faq.md)。

实际案例分析#

案例1：代码审查Skill#

markdown
复制
---
name: code-reviewer
description: 进行代码审查和质量检查。当用户提交代码审查请求或需要代码质量分析时使用此Skill。
---

# 代码审查助手

## 审查流程

1. **代码结构分析**
   - 检查文件组织
   - 验证命名规范
   - 评估模块化程度

2. **质量检查**
   - 识别代码异味
   - 检查安全漏洞
   - 验证测试覆盖率

3. **改进建议**
   - 提供具体修改建议
   - 解释改进理由
   - 建议最佳实践

## 审查标准

- **可读性**：代码是否易于理解
- **可维护性**：代码是否易于修改
- **性能**：是否存在性能问题
- **安全性**：是否存在安全风险

## 特殊场景处理

### 紧急修复
优先检查关键功能的完整性

### 新功能开发
重点关注设计模式和架构决策

### 重构任务
评估重构的影响和风险

案例2：文档生成Skill#

markdown
复制
---
name: doc-generator
description: 生成项目文档和API说明。当用户需要创建README、技术文档或API文档时使用此Skill。
---

# 文档生成助手

## 文档类型

### 项目文档
- README.md：项目简介和使用指南
- CONTRIBUTING.md：贡献指南
- CHANGELOG.md：版本变更记录

### 技术文档
- API文档：接口说明和使用示例
- 架构文档：系统设计和组件关系
- 部署文档：安装和配置指南

## 生成流程

1. **需求分析**：确定文档类型和受众
2. **内容收集**：从代码和注释中提取信息
3. **结构组织**：按照标准格式组织内容
4. **格式优化**：使用Markdown语法美化文档

## 质量保证

- 确保信息准确性和完整性
- 使用一致的格式和术语
- 提供实用的示例和链接

最佳实践总结#

  1. 保持简洁：用最少的token表达最多信息
  2. 结构清晰：使用标题和列表组织内容
  3. 条件明确：精确描述使用时机
  4. 渐进式披露：核心信息在前，详细信息引用外部文件
  5. 持续迭代：根据实际使用情况优化指令

通过精心设计的SKILL.md文件，你可以创建出专业、可靠且易于维护的Skills。记住，好的指令就像好的老师，能够清晰地引导Claude完成复杂的任务。