Skill 文件结构详解
创建一个能运行的 Skill 最少只需要一个文件。但"能运行"和"好用"之间的差距，在于文件结构是否合理。这一节详细拆解 Skill 文件的每个组成部分。
最小可用 Skill
下面是一个完整的、可以立刻使用的 Skill：
---
description: 对当前项目生成代码质量摘要报告
---
# 代码质量检查
## 目标
分析当前项目的代码质量，生成一份简洁的摘要报告。
## 执行步骤
1. 用 Glob 工具找出项目中所有 `.ts`、`.js`、`.py` 文件
2. 用 Grep 工具搜索常见问题模式：
- `TODO` / `FIXME` 注释
- `console.log` / `print(` 调试语句（生产代码中不应出现）
- 超长函数（单文件超过 500 行）
3. 统计每类问题的数量和位置
4. 输出结构化报告
## 输出格式
使用以下格式输出：
代码质量摘要
扫描范围：[文件数量] 个源文件
发现的问题
| 类型 | 数量 | 高风险位置 |
|---|---|---|
| TODO/FIXME | N | file:line |
| 调试语句 | N | file:line |
建议优先处理
[列出最需要关注的 3 个问题]
把这个文件保存为 .claude/skills/code-quality.md，然后输入 /code-quality 即可运行。
文件结构的五个区域
┌─────────────────────────────────────────────────┐
│ --- (YAML frontmatter) │ ← 区域 1：元数据
│ description: ... │
│ allowed-tools: ... │
│ --- │
├─────────────────────────────────────────────────┤
│ # Skill 标题 │ ← 区域 2：标题
├─────────────────────────────────────────────────┤
│ ## 目标 / 背景 │ ← 区域 3：上下文设定
│ （告诉 Claude 这个 Skill 的用途） │
├─────────────────────────────────────────────────┤
│ ## 执行步骤 │ ← 区域 4：核心指令
│ （详细的步骤列表，Claude 按此执行） │
├─────────────────────────────────────────────────┤
│ ## 输出格式 │ ← 区域 5：输出规范
│ （期望的输出结构和格式） │
└─────────────────────────────────────────────────┘
区域 1：YAML Frontmatter
---
description: 一句话说明这个 Skill 做什么（显示在 /help 列表中）
allowed-tools: Read, Write, Bash, Grep, Glob
---
description 字段：
- 用一句话概括 Skill 的用途
- 在用户执行 /help 时显示
- 帮助团队成员快速了解 Skill 的功能
- 建议不超过 80 个字符
allowed-tools 字段：
- 声明这个 Skill 可以使用的工具列表
- 如果省略，Claude 会根据推理选择合适的工具
- 显式声明可以提高安全性（限制 Skill 的操作范围）
- 可用工具：Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch
区域 3：上下文设定的重要性
这个区域经常被初学者忽略，但它对 Skill 的执行质量影响很大。
差的上下文设定：
## 目标
检查代码。
好的上下文设定：
## 目标
对当前 Git 仓库中最近修改的文件进行代码审查，重点关注：
- 安全漏洞（SQL 注入、XSS、硬编码密钥）
- 错误处理缺失（空指针、未捕获异常）
- 代码可读性（函数名、变量名是否清晰）
此 Skill 面向后端 Node.js/TypeScript 项目，审查标准参考 OWASP Top 10。
好的上下文设定给 Claude 足够的背景，让它能做出符合预期的判断。
区域 4：执行步骤的写法
执行步骤是 Skill 的核心，决定 Claude 会做什么。有效的步骤描述应该：
明确、可执行：
## 执行步骤
1. 运行 `git diff --name-only HEAD~1 HEAD` 获取本次提交修改的文件列表
2. 对每个修改的文件，使用 Read 工具读取文件内容
3. 分析每个文件是否存在以下问题：...
4. 汇总所有问题，生成报告
避免模糊指令：
# ❌ 太模糊
## 执行步骤
1. 看看代码
2. 告诉我有什么问题
# ✅ 具体可执行
## 执行步骤
1. 使用 Bash 工具运行：git log --oneline -10
2. 读取最近修改的 3 个文件
3. 检查每个函数是否有对应的单元测试
区域 5：输出格式规范
明确的输出格式让 Skill 的结果可预期、可解析：
## 输出格式
严格使用以下 Markdown 格式输出，不要添加额外的解释：
审查结果：{{filename}}
总体评分：[1-5 分] / 5
严重问题（必须修复）
- [ ] 问题描述（行号：XX）
改进建议（可选）
- 建议描述
通过检查
- ✅ 通过的检查项
如果没有发现问题，输出：
`✅ {{filename}} 通过所有检查项`
完整示例：git-summary Skill
---
description: 生成最近 N 次提交的工作摘要（适合站会使用）
allowed-tools: Bash
---
# Git 工作摘要
## 目标
生成当前 Git 仓库最近提交的工作摘要，格式适合在站会或周报中使用。
## 执行步骤
1. 运行 `git log --oneline --since="7 days ago"` 获取最近 7 天的提交
2. 运行 `git log --stat --since="7 days ago"` 获取修改的文件统计
3. 按照以下维度归纳提交内容：
- 新功能（feat）
- Bug 修复（fix）
- 重构（refactor）
- 文档（docs）
- 其他
4. 生成摘要报告
## 输出格式
本周工作摘要（最近 7 天）
提交总数：N 次
新功能
- 功能描述（基于 commit message）
Bug 修复
- 问题描述
其他变更
- 描述
主要修改文件： - 文件路径（修改次数）
下一节：在 .claude/skills/ 中组织 Skill——一个项目里有多个 Skill 时，如何组织目录结构？