# 技能模板

用于从 learnings 中提炼 skill 的模板。复制后按需修改。

---

## SKILL.md 模板

```markdown
---
name: skill-name-here
description: "简洁说明此 skill 适用于什么问题、为什么要使用它，并写明触发条件。"
---

# 技能名称

简要说明这个 skill 解决的问题，以及它来自哪条 learning。

## 快速参考

| 场景 | 动作 |
|-----------|--------|
| [触发条件 1] | [动作 1] |
| [触发条件 2] | [动作 2] |

## 背景

说明这条知识为什么重要、能预防什么问题，以及原始 learning 中的关键上下文。

## 解决方案

### 分步说明

1. 第一步，附上代码或命令
2. 第二步
3. 验证步骤

### 代码示例

\`\`\`language
// 用示例代码展示解决方案
\`\`\`

## 常见变体

- **变体 A**：说明是什么，以及怎么处理
- **变体 B**：说明是什么，以及怎么处理

## 注意事项

- 常见警告或易错点 1
- 常见警告或易错点 2

## 相关内容

- 链接到相关文档
- 链接到相关 skill

## 来源

由 learning 条目提炼而来。
- **Learning ID**：LRN-YYYYMMDD-XXX
- **原始分类**：correction | insight | knowledge_gap | best_practice
- **提炼日期**：YYYY-MM-DD
```

---

## 精简模板

适用于不需要完整章节的简单 skill：

```markdown
---
name: skill-name-here
description: "说明这个 skill 做什么，以及在什么情况下使用。"
---

# 技能名称

[用一句话描述问题]

## 解决方案

[直接给出解决方案与代码/命令]

## 来源

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## 带脚本的模板

适用于包含可执行辅助脚本的 skill：

```markdown
---
name: skill-name-here
description: "说明这个 skill 做什么，以及在什么情况下使用。"
---

# 技能名称

[简介]

## 快速参考

| 命令 | 用途 |
|---------|---------|
| `./scripts/helper.sh` | [作用说明] |
| `./scripts/validate.sh` | [作用说明] |

## 用法

### 自动化方式（推荐）

\`\`\`bash
./skills/skill-name/scripts/helper.sh [args]
\`\`\`

### 手动步骤

1. 第一步
2. 第二步

## 脚本

| 脚本 | 说明 |
|--------|-------------|
| `scripts/helper.sh` | 主工具脚本 |
| `scripts/validate.sh` | 校验脚本 |

## 来源

- Learning ID: LRN-YYYYMMDD-XXX
```

---

## 命名约定

- **技能名称**：全部小写，空格使用连字符
  - 好例子：`docker-m1-fixes`、`api-timeout-patterns`
  - 差例子：`Docker_M1_Fixes`、`APITimeoutPatterns`

- **Description**：以动作动词开头，并写明触发条件
  - 好例子："处理 Apple Silicon 上的 Docker build 失败问题。当构建因平台不匹配报错时使用。"
  - 差例子："Docker stuff"

- **文件结构**：
  - `SKILL.md` - 必需，主文档
  - `scripts/` - 可选，可执行代码
  - `references/` - 可选，详细文档
  - `assets/` - 可选，模板文件

---

## 提炼检查清单

从一条 learning 创建 skill 之前，确认：

- [ ] Learning 已验证（状态为 `resolved`）
- [ ] 方案适用范围广（不是一次性问题）
- [ ] 内容完整（具备所需上下文）
- [ ] 名称符合约定
- [ ] Description 简洁但信息充分
- [ ] 快速参考表可直接执行
- [ ] 代码示例已测试
- [ ] 已记录来源 learning ID

创建后，确认：

- [ ] 更新原始 learning，状态改为 `promoted_to_skill`
- [ ] 在 learning metadata 中加入 `Skill-Path: skills/skill-name`
- [ ] 在新的 session 中读取 skill，确认其自洽可用