# 六步创建 Skill 详解

## 第1步：搞清楚需求

创建前先回答 6 个问题：

| # | 问题 | 为什么问 |
|---|------|---------|
| 1 | 什么场景触发这个 Skill？ | 对应 frontmatter description 触发词 |
| 2 | AI 有相应能力吗？ | 没能力的话要么加代码，要么不做 |
| 3 | 用户输入什么？AI 输出什么？ | 输入输出界定不清楚 → Inversion 模式 |
| 4 | 用 Tool Wrapper / Generator / Reviewer / Inversion / Pipeline？ | 选错模式后面全错 |
| 5 | 依赖什么外部资源？ | 路径/API/凭证要写清楚 |
| 6 | 谁维护？预期谁用？ | 决定详细度、团队分支策略 |

## 第2步：规划资源

| 目录 | 用途 | 是否需要 |
|------|------|---------|
| `scripts/` | 可执行脚本（py/sh/ps1） | 有自动化逻辑时需要 |
| `references/` | 参考文档/配置文件 | 内容超过 30 行时建议拆 |
| `assets/` | 图片/模板文件 | 有模板/示例文件时需要 |

## 第3步：生成骨架

```bash
clawhub init-skill my-new-skill
# 或手动创建：
mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md
```

## 第4步：写正文 + 补资源

参考顺序：先做资源 → 再写 SKILL.md。

### 头部（frontmatter）

```yaml
---
name: my-skill
description: "一句话说清做什么，触发词是关键。"    # ⭐ 最重要！
metadata:
  version: "1.0"
  updated: "2026-05-12"
  owner: "Ronie"
---
```

### 正文怎么写

| 层 | 内容 | 说明 |
|----|------|------|
| 层0 | 一句话总览 | AI 看了就知道要不要继续读 |
| 层1-2 | 核心流程 | 最少步骤完成工作 |
| 层3-4 | 参数/配置细节 | 第4层开始用 `> 详细见 references/xxx.md` |
| 层5-6 | 故障排查/高级话题 | 只在需要时读 |

### 渐进加载的三种写法

```markdown
# 写法A：外部文件引用（推荐）
> 完整模式说明见 [references/design-patterns.md](references/design-patterns.md)

# 写法B：折叠块（直接在 SKILL.md 里折叠）
<details>
<summary>故障排查细节（点击展开）</summary>
...
</details>

# 写法C：只留链接
> 详细示例见 [references/examples.md](references/examples.md)
```

## 第5步：打包

```bash
clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0
```

## 第6步：迭代改进

治理规范（Skill 进入团队工作流以后）：

| 角色 | 职责 |
|------|------|
| Owner | 审核变更、修 issue、确保文档和代码匹配 |
| Reviewer | 每次发布前审查：描述是否准确、示例是否过时 |
| User | 提 issue、提使用反馈 |