Skill 文件结构
一个 Agent Skill 本质上是一个文件夹，核心是 SKILL.md 文件。理解文件结构是编写高质量 Skill 的基础。
基本结构
最简单的 Skill 只需要一个文件夹和一个 SKILL.md 文件：
my-skill/
└── SKILL.md
这是 Skill 的最小可行单元。SKILL.md 文件包含两部分：YAML frontmatter（元数据）和 Markdown 正文（指令内容）。
SKILL.md 文件详解
完整示例
---
name: "python-code-reviewer"
description: "审查 Python 代码质量，检查 PEP 8 规范、类型注解、文档字符串。当用户请求代码审查或提交 Python 代码时触发。"
---
# Python 代码审查专家
你是一位专业的 Python 代码审查员，精通 PEP 8 规范和 Python 最佳实践。
## 审查范围
### 代码风格
- 检查命名规范（变量、函数、类）
- 检查缩进和空格使用
- 检查行长度（建议不超过 88 字符）
### 类型注解
- 检查函数参数和返回值的类型注解
- 验证类型注解的正确性
### 文档
- 检查 docstring 是否存在
- 验证 docstring 格式（Google/NumPy/Sphinx 风格）
## 输出格式
请按以下格式输出审查结果：
1. **问题列表**：按严重程度排序
- 🔴 严重：可能导致错误的问题
- 🟡 警告：代码风格问题
- 🔵 建议：优化建议
2. **改进建议**：针对每个问题给出具体修改方案
3. **总体评价**：简要总结代码质量
YAML Frontmatter
SKILL.md 文件以 YAML frontmatter 开头，用三个连字符 --- 包围。Frontmatter 定义了 Skill 的元数据。
必需字段
| 字段 | 类型 | 限制 | 说明 |
|---|---|---|---|
name | string | 小写字母、数字、连字符，不超过 64 字符 | Skill 的唯一标识符 |
description | string | 不超过 1024 字符 | 描述 Skill 的功能和触发条件 |
name 字段规范
name 是 Skill 的标识符，需要遵循以下规则：
✅ 正确示例
name: "code-reviewer"
name: "python-linter"
name: "api-doc-generator"
name: "test-writer-v2"
❌ 错误示例
name: "Code Reviewer" # 包含大写字母
name: "code_reviewer" # 使用下划线而非连字符
name: "代码审查" # 包含非 ASCII 字符
name: "a-very-long-skill-name-that-exceeds-the-64-character-limit" # 超过 64 字符
description 字段规范
description 是决定 Skill 何时被触发的关键字段。它需要同时说明：
- 功能描述：这个 Skill 做什么
- 触发条件：什么时候应该使用这个 Skill
✅ 好的 description
description: "审查 Python 代码质量，检查 PEP 8 规范。当用户请求代码审查或提交 Python 代码时触发。"
❌ 太模糊
description: "帮助写代码" # 不清楚具体功能
❌ 太宽泛
description: "处理所有编程相关问题" # 可能导致过度触发
❌ 缺少触发条件
description: "Python 代码审查工具" # 没有说明何时使用
可选字段
除了必需字段，frontmatter 还可以包含可选字段：
---
name: "api-doc-generator"
description: "为 REST API 生成文档。当用户需要生成 API 文档时触发。"
version: "1.0.0"
author: "your-name"
tags:
- api
- documentation
- rest
---
Markdown 正文
Frontmatter 之后是 Markdown 格式的正文，这是给 AI 的具体指令。正文内容决定了 Skill 的实际效果。
正文结构建议
一个结构良好的正文通常包含以下部分：
# 标题（定义角色）
简要说明 AI 在这个 Skill 中扮演什么角色。
## 核心职责
列出主要任务和关注点。
## 工作流程
描述执行任务的步骤。
## 输出格式
定义输出的结构和样式。
## 注意事项
列出需要避免的问题或特殊情况。
目录结构变体
包含资源文件的 Skill
如果 Skill 需要引用模板、配置或其他资源文件，可以添加额外的文件：
my-skill/
├── SKILL.md
├── templates/
│ ├── api-doc.md
│ └── readme.md
└── config/
└── rules.json
在 SKILL.md 中可以引用这些文件：
---
name: "doc-generator"
description: "生成项目文档。当用户需要生成 README 或 API 文档时触发。"
---
# 文档生成器
使用项目根目录下的 templates/ 文件夹中的模板生成文档。
## 可用模板
- `templates/readme.md`：README 模板
- `templates/api-doc.md`：API 文档模板
多文件 Skill
对于复杂的工作流，可以将指令拆分到多个文件：
code-quality-skill/
├── SKILL.md # 主入口
├── linting.md # 代码检查规则
├── formatting.md # 格式化规则
└── testing.md # 测试规范
主 SKILL.md 可以引用其他文件：
---
name: "code-quality"
description: "全面的代码质量检查。当用户请求代码质量检查时触发。"
---
# 代码质量检查器
本 Skill 包含以下检查模块：
1. 代码检查（参考 linting.md）
2. 格式化检查（参考 formatting.md）
3. 测试规范检查（参考 testing.md）
请依次执行以上检查。
存放位置
不同工具对 Skill 存放位置有不同的约定：
Claude Code
项目根目录/
├── .claude/
│ └── skills/
│ ├── code-reviewer/
│ │ └── SKILL.md
│ └── doc-generator/
│ └── SKILL.md
└── ...
Trae IDE
项目根目录/
├── .trae/
│ └── skills/
│ ├── code-reviewer/
│ │ └── SKILL.md
│ └── doc-generator/
│ └── SKILL.md
└── ...
Cursor
项目根目录/
├── .cursor/
│ └── skills/
│ ├── code-reviewer/
│ │ └── SKILL.md
│ └── doc-generator/
│ └── SKILL.md
└── ...
全局 Skills
除了项目级别的 Skills，还可以创建全局 Skills，适用于所有项目：
用户目录/
├── .claude/
│ └── skills/
│ └── global-skill/
│ └── SKILL.md
文件编码
SKILL.md 文件应使用 UTF-8 编码，确保中文字符正常显示。
命名规范
文件夹命名
- 使用小写字母
- 单词之间用连字符连接
- 名称应简洁且具有描述性
✅ 好的命名
code-reviewer/
python-linter/
api-doc-generator/
❌ 不好的命名
CodeReviewer/ # 大写字母
code_reviewer/ # 下划线
skill1/ # 无意义名称
与 name 字段的关系
文件夹名称和 SKILL.md 中的 name 字段最好保持一致，便于管理：
code-reviewer/
└── SKILL.md # name: "code-reviewer"
小结
理解 Skill 的文件结构是编写高质量 Skill 的第一步。记住以下要点：
- 最小结构：一个文件夹 + 一个 SKILL.md 文件
- 必需字段：name 和 description 是 frontmatter 的必需字段
- description 关键：清晰描述功能和触发条件
- 正文结构：角色定义、职责、流程、输出格式
- 存放位置：遵循各工具的约定
下一步，我们将学习 如何编写高质量的 Skill。