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完成复杂的任务。