Skill的结构

理解 Skill 的目录结构和 SKILL.md 的写法，是写出高质量 Skill 的基础。本篇详细讲。

1. 完整目录结构

一个 Skill 可以从最简单的 SKILL.md 开始，逐渐扩展为包含多种资源的完整结构：

my-skill/
├── SKILL.md              # 必需：Skill 主文档
├── reference/            # 可选：参考资料（详细文档）
│   ├── conventions.md
│   └── examples.md
├── templates/            # 可选：模板文件
│   ├── api_handler.py.tpl
│   └── test_template.py.tpl
├── scripts/              # 可选：辅助脚本
│   ├── lint.sh
│   └── analyze.py
└── assets/               # 可选：图片、示例文件等
    └── architecture.png

只有 SKILL.md 是必需的，其他都可选。

2. SKILL.md 的标准结构

---
name: my-skill
description: 简短清晰说明何时使用这个 Skill
---

# Skill 标题

简介：这个 Skill 是做什么的，解决什么问题。

## 何时使用

明确说明触发场景。

## 工作步骤

详细步骤，最好编号。

## 输入要求

用户应该提供什么。

## 输出要求

期望的产出格式。

## 示例

一个或多个完整示例。

## 注意事项

常见误区、边界情况。

## 参考资料

引用其他文件（如果有）。

不是所有部分都必须有，根据 Skill 复杂度灵活取舍。

3. Frontmatter 详解

Frontmatter 是 SKILL.md 顶部用 --- 包围的 YAML 块。这部分会一直出现在 Claude 的上下文中（不管 Skill 内容有多长），所以控制好长度很重要。

必需字段

---
name: code-reviewer
description: 当用户要求 code review 时使用，按公司规范进行严格的代码审查
---

字段	类型	说明
`name`	string	Skill 唯一标识，使用 kebab-case，对应文件夹名
`description`	string	触发条件说明，强烈建议 < 200 字符

可选字段

不同 Claude 产品支持的可选字段略有差异，常见的有：

---
name: deploy-helper
description: 用于部署相关任务时调用
allowed-tools:
  - Bash
  - Read
  - Edit
---

allowed-tools 可以限制 Skill 工作时能使用的工具，提高安全性。

4. Description 写作技巧

description 是 Skill 触发的核心信号。模型只看到 description 就要决定是否加载完整 SKILL.md，所以：

三段式结构最有效

当 [触发条件] 时使用，[做什么]，[输出特点]

示例：

当用户要求生成 API 文档时使用，从代码注释和函数签名提取信息，输出 OpenAPI 3.1 规范的 YAML

包含触发关键词

description 中要包含用户实际会说的词：

❌ "处理数据预处理工作" ✅ "清洗 CSV、Excel 数据，处理缺失值、去重、格式转换"

后者明确包含 "CSV"、"Excel"、"清洗" 等用户表达，命中率更高。

避免过于宽泛

❌ "代码相关任务" ✅ "对 Python/JavaScript 代码进行安全审计，检查 SQL 注入、XSS、路径穿越等漏洞"

宽泛的 description 要么不触发（模型不确定该用），要么乱触发（什么都用）。

5. 主文档（正文）写作

正文是 Claude 实际加载后会读到的部分，可以写得详细。但仍要遵循一些原则：

简洁优先

Claude 上下文有限，写过长的 SKILL.md 反而稀释信息。1000-3000 字最佳。

结构化

用清晰的标题、列表、表格组织内容，让模型容易抓重点。

给出明确指令

❌ 含糊：

你应该考虑代码质量。

✅ 明确：

检查每个函数： 1. 行数是否超过 50 行 2. 是否有未处理的异常 3. 命名是否使用有意义的英文单词

提供示例

示例胜过千言万语：

## 示例

输入：
```python
def f(x): return x*2
```

输出：
```python
def double(x: int) -> int:
    """Return x multiplied by two."""
    return x * 2
```

6. 引用辅助文件

复杂 Skill 通常需要拆分到多个文件。SKILL.md 用相对路径引用：

## 详细规范

参考 [reference/conventions.md](reference/conventions.md) 获取完整的命名规范和模式列表。

## 项目模板

使用 [templates/api_handler.py.tpl](templates/api_handler.py.tpl) 作为新 API 处理器的起点。

Claude 会按需加载这些引用文件——只有它判断需要时才读，不会一开始就吃光上下文。

7. 渐进式加载策略

利用 Claude 的渐进式加载，可以这样组织 SKILL.md：

---
name: react-component-generator
description: 当用户要求创建新的 React 组件时使用，按公司风格生成 TSX + 测试 + Story
---

# React 组件生成器

## 工作步骤

1. 询问组件名称和用途
2. 创建组件文件 `src/components/<Name>/<Name>.tsx`
3. 创建测试 `src/components/<Name>/<Name>.test.tsx`
4. 创建 Story `src/components/<Name>/<Name>.stories.tsx`

## 风格要求

详见 [reference/style-guide.md](reference/style-guide.md)（仅在需要参考具体规范时阅读）

## 模板

- 组件：[templates/component.tsx.tpl](templates/component.tsx.tpl)
- 测试：[templates/test.tsx.tpl](templates/test.tsx.tpl)
- Story：[templates/story.tsx.tpl](templates/story.tsx.tpl)

## 命名规范

- 组件名：PascalCase
- 文件名：与组件名一致
- props 接口名：`<ComponentName>Props`

这样 Claude：

先看到主文档（核心步骤）
真正生成代码时再读取模板文件
遇到不确定的风格问题才查 style-guide.md

8. 写好的 SKILL.md 示例

下面是一个综合示例：SQL 查询审查 Skill：

---
name: sql-reviewer
description: 当用户要求审查、优化或检查 SQL 查询时使用，识别性能问题、N+1、安全风险并给出具体优化建议
---

# SQL Reviewer

对用户提供的 SQL 查询进行专业审查，识别性能问题、安全风险并提出优化建议。

## 审查维度

### 1. 性能

- [ ] 是否有全表扫描（缺少 WHERE 或索引）
- [ ] JOIN 顺序是否合理（小表在前）
- [ ] 是否使用了 SELECT *（应该指定具体列）
- [ ] LIMIT 是否合理使用
- [ ] 是否有可能的 N+1 查询模式（建议改为 JOIN 或 IN）

### 2. 安全

- [ ] 是否有 SQL 注入风险（拼接字符串、未参数化）
- [ ] 是否有越权访问风险（缺少 user_id 等过滤）

### 3. 正确性

- [ ] NULL 值处理是否正确（IS NULL vs = NULL）
- [ ] 字符串比较是否考虑大小写
- [ ] 时区是否处理

### 4. 可读性

- [ ] 表别名是否有意义
- [ ] 是否有不必要的子查询
- [ ] 复杂逻辑是否拆分为 CTE

## 输出格式

按以下格式输出审查报告：

````
## 总体评价
（1-2 句话）

## 严重问题（必须修复）
1. [行号] 问题描述
   - 原因：...
   - 建议：...

## 优化建议（推荐改进）
1. [行号] ...

## 优化后的 SQL
```sql
（重写后的查询）
```
````

## 示例

输入：
```sql
SELECT * FROM users WHERE name = '" + name + "';
```

输出：
- 严重：SQL 注入风险，使用参数化查询
- 严重：使用 SELECT *，应指定列
- 优化后：
  ```sql
  SELECT id, name, email FROM users WHERE name = ?;
  ```

9. Frontmatter 长度建议

由于 frontmatter 始终在上下文中，过多的 Skill 会累积。控制策略：

description 控制在 200 字符以内
总 Skill 数量超过 30 个时，逐个 review，删除不常用的
同类 Skill 合并（不要为每个语言写一个 docstring Skill）

10. 文件名和命名规范

文件夹名和 name 字段保持一致：code-reviewer/ ↔ name: code-reviewer
使用 kebab-case：api-doc-generator，不要 apiDocGenerator 或 api_doc_generator
SKILL.md 必须全大写：不是 skill.md 也不是 Skill.md
辅助文件用小写：reference/conventions.md、scripts/lint.sh

总结

Skill 目录最小只需要 SKILL.md，可扩展为包含 reference/templates/scripts/assets 的完整结构
Frontmatter 的 name 和 description 是关键，description 决定触发
description 写法：三段式 + 关键词 + 避免宽泛，控制在 200 字符以内
SKILL.md 主文档 1000-3000 字最佳，太长稀释信息
用相对路径引用辅助文件，利用渐进式加载控制上下文消耗
命名规范：文件夹和 name 一致，全部 kebab-case，SKILL.md 大写