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

约 2125 字大约 7 分钟

概述

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

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

YAML Frontmatter规范

必需字段

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

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

# Skill标题

Skill的具体内容...

name: Skill的唯一标识符

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

只允许小写字母、数字和连字符
长度限制：1-64个字符
建议使用描述性名称，如 code-reviewer、data-analyzer
description: Skill的功能描述和触发条件

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

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

name: Skill的唯一标识符

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

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

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

可选字段

---
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能够快速定位信息：

# 数据分析助手

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

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

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

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

## 示例
实际使用案例

2. 使用清晰的语言

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

不好的示例：

3. 条件触发设置

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

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

# Excel处理助手

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

引用外部文件

基本引用语法

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

# 数据处理Skill

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

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

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

引用时机选择

何时使用引用：

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

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

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

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

何时使用引用：

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

何时保留在主文件：

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

渐进式披露策略

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

# 数据库管理助手

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

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

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

条件触发和上下文感知

基于任务类型的触发

## 适用场景

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

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

基于用户意图的触发

## 意图识别

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

Token优化技巧

1. 精简表达

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

2. 标准化表述

使用一致的格式和术语：

## 操作清单

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

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

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

3. 条件加载

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

## 高级配置

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

## 故障排除

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

实际案例分析

案例1：代码审查Skill

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

# 代码审查助手

## 审查流程

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

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

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

## 审查标准

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

## 特殊场景处理

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

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

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

案例2：文档生成Skill

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

# 文档生成助手

## 文档类型

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

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

## 生成流程

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

## 质量保证

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

最佳实践总结

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

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