# Frontmatter 编写规范

Frontmatter 是 Skill 的"身份证"，决定了 Skill 何时被触发、是否被正确识别。编写不当会导致 Skill 永远不会被使用。

---

## 1. 必须字段

### 1.1 name

**规则**：
- 小写字母 + 数字 + 连字符（`-`）
- 动名词形式开头（`developing-`、`managing-`、`implementing-`、`designing-`）
- ≤ 64 字符
- 包含模块名或领域名

**常用前缀**：
| 前缀 | 适用场景 |
|------|---------|
| `developing-` | 模块开发、功能实现 |
| `managing-` | 管理类操作（DB、配置、部署） |
| `implementing-` | 特定技术方案实现 |
| `designing-` | 设计阶段的规范和契约 |
| `writing-` | 编写文档、脚本、测试 |

**示例**：
```yaml
# ✅ 正确
name: developing-work-procedure
name: managing-db-migrations
name: implementing-totp-auth

# ❌ 错误
name: WorkProcedure          # 不能大写
name: work_procedure         # 不能用下划线
name: wp                     # 太短，无法触发
```

### 1.2 description

**这是最关键的字段** —— 决定 Skill 是否能被正确触发。

**硬性规则**：
1. **必须单行**（不换行） —— 换行会导致 YAML 解析出错，Skill 静默失败
2. **< 1024 字符**
3. **第三人称**描述
4. **中英文混合** —— 确保中文和英文查询都能命中
5. **包含触发场景**（Trigger）和**关键词**（Keywords）

**结构模板**：
```
<功能概述（中英文）>。包含：<具体能力列表>。触发场景 Trigger: <场景列表>。关键词 Keywords: <关键词列表>。
```

**示例**：
```yaml
# ✅ 正确（单行，中英文混合，包含触发场景和关键词）
description: 指导 rmdc-work-procedure 工单流程模块的开发（Guides development of rmdc-work-procedure workflow module）。包含：状态机实现、工单 CRUD、并发控制、WebSocket 事件。触发场景 Trigger: 修改工单表 / 添加工单类型 / 变更状态转换 / 实现工单 API。关键词 Keywords: workflow, work-procedure, state-machine, 工单, 状态机, 流转。

# ❌ 错误 - 多行（会静默失败！）
description: |
  指导工单模块开发。
  包含状态机实现。

# ❌ 错误 - 太短，无关键词
description: 工单模块开发指导

# ❌ 错误 - 纯英文，中文查询无法命中
description: Guides the development of workflow module with state machine
```

**推动触发的技巧**：
- Claude 有"不触发"的倾向，所以 description 应该稍微"激进"一些
- 多列出触发场景，覆盖用户可能的表述方式
- 包含同义词（如：工单/workflow/ticket）

### 1.3 argument-hint

**规则**：
- 说明 `$ARGUMENTS` 的期望格式
- 给出 2~3 个具体示例

**示例**：
```yaml
argument-hint: "<action> <target> - e.g., 'create handler user', 'add api /workflow/create', 'update schema workflows'"
```

---

## 2. 可选字段

### 2.1 allowed-tools

**原则**：最小授权 —— 只声明 Skill 真正需要的工具。

| 工具 | 适用场景 |
|------|---------|
| `Read` | 读取文件（几乎总是需要） |
| `Glob` | 搜索文件（几乎总是需要） |
| `Grep` | 搜索文件内容（几乎总是需要） |
| `Bash` | 执行 shell 命令（按需） |
| `Write` | 创建新文件（开发类 Skill 需要） |
| `Edit` | 编辑现有文件（开发类 Skill 需要） |

**示例**：
```yaml
# 只读 Skill（审查/分析类）
allowed-tools:
  - Read
  - Glob
  - Grep

# 开发 Skill（需要写文件）
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
```

---

## 3. YAML 格式注意事项

### 3.1 多行 description 的安全写法

如果 description 确实很长，使用 `>` 折叠块语法（注意：这仍然会被解析为单行）：

```yaml
description: >
  指导 rmdc-work-procedure 工单流程模块的开发。
  包含状态机实现、工单 CRUD、并发控制。
  触发场景 Trigger: 修改工单表、添加工单类型。
```

> ⚠️ 使用 `>` 时，YAML 会将换行替换为空格，最终合并为单行。这是安全的。
> ❌ 绝不要使用 `|`（保留换行块语法），那会导致多行 description。

### 3.2 特殊字符转义

```yaml
# 包含冒号时用引号包裹
argument-hint: "<action>: <target>"

# 包含 # 时用引号
description: "指导 C# 项目开发"
```

---

## 4. 自检清单

- [ ] `name` 为动名词形式、小写连字符、≤ 64 字符
- [ ] `description` 在最终 YAML 中为单行
- [ ] `description` < 1024 字符
- [ ] `description` 包含中文和英文
- [ ] `description` 包含触发场景（Trigger）
- [ ] `description` 包含关键词（Keywords）
- [ ] `argument-hint` 有具体示例
- [ ] `allowed-tools` 遵循最小授权
