---
name: skill-creator-yashu
description: 创建新 skill。何时使用：当用户说"创建 skill"、"新建 skill"、"添加 skill"、"初始化 skill"时。
metadata:
  author: 牙叔教程
  updated: "2026-02-24 00:00:00"
  version: "1.1.0"
---

## 🎯 触发映射

| 用户输入触发词                                              | AI 执行动作        |
| ----------------------------------------------------------- | ------------------ |
| "创建 skill" / "新建 skill" / "添加 skill" / "初始化 skill" | 按【创建模式】执行 |

---

## 创建模式

### 执行步骤

| 步骤 | 执行动作         | 具体命令/操作                                                                          |
| ---- | ---------------- | -------------------------------------------------------------------------------------- |
| 1    | 询问需求         | 运行 `AskUserQuestion` 询问用户 skill 功能、使用场景和触发条件                         |
| 2    | 初始化目录       | 运行 `RunCommand` 执行 `python scripts/init_skill.py <skill-name> --path <output-dir>` |
| 3    | 读取并编辑 SKILL | 运行 `Read` 读取生成的 SKILL.md，运行 `SearchReplace` 填写功能描述和触发条件           |
| 4    | 验证结构         | 运行 `RunCommand` 执行 `python scripts/quick_validate.py <skill-directory>`            |

### 输出结果

**成功时输出示例：**

```
✅ Skill '{skill-name}' 创建成功

📁 目录结构：
.trae/skills/{skill-name}/
├── SKILL.md          # 技能文档（已填充模板）
├── scripts/          # 脚本目录
│   └── example.py    # 示例脚本
└── references/       # 参考文档目录
    └── README.md     # 参考说明

📝 下一步：
运行 `Read` 读取 SKILL.md，根据用户需求编辑功能描述和触发条件
```

**失败时输出示例：**

```
❌ Skill 创建失败

错误原因：{具体错误信息}
解决建议：{针对性解决方案}
```

### 错误处理

| 错误场景       | 错误表现               | 处理方式                                                         |
| -------------- | ---------------------- | ---------------------------------------------------------------- |
| 目录已存在     | `mkdir` 报错目录已存在 | 运行 `LS` 检查目录内容，如为空则继续，如有内容则询问用户是否覆盖 |
| 脚本执行失败   | Python 返回非零退出码  | 检查 Python 版本、依赖安装情况，重试执行                         |
| 权限不足       | 文件写入被拒绝         | 检查目录权限，建议用户更换输出目录                               |
| skill 名称无效 | 含大写或特殊字符       | 提示用户修改为 kebab-case 格式（如 `my-skill`）                  |

## 核心原则

### 简洁至上 (Concise is Key)

上下文窗口是公共资源。Skill 与系统提示词、对话历史、其他 Skill 的元数据以及用户请求共享上下文窗口。

**默认假设：AI 已经很聪明了。** 只添加 AI 没有的信息。质疑每一条信息："AI 真的需要这个解释吗？" "这段文字值得它的 token 成本吗？"

优先使用简洁的例子而非冗长的解释。

### 设置适当的自由度

根据任务的脆弱性和可变性匹配合适的详细程度：

| 自由度       | 适用场景                                             | 形式                 |
| ------------ | ---------------------------------------------------- | -------------------- |
| **高自由度** | 多种方法都有效、决策依赖上下文、启发式指导方法       | 基于文本的指令       |
| **中自由度** | 存在首选模式、允许一定变化、配置影响行为             | 伪代码或带参数的脚本 |
| **低自由度** | 操作脆弱且容易出错、一致性至关重要、必须遵循特定序列 | 特定脚本、少量参数   |

### AI 友好性 (AI-Friendly)

**Skill 是给 AI 使用的**，必须确保 AI 能够准确理解和执行。创建的 skill 必须符合以下 AI 友好性标准：

| 检查项                 | 要求 | 说明                                                |
| ---------------------- | ---- | --------------------------------------------------- |
| **清晰的 description** | 必须 | frontmatter 中的 description 必须包含功能和触发条件 |
| **明确的指令**         | 必须 | 使用祈使句（运行、执行、调用等）而非模糊建议        |
| **具体的示例**         | 必须 | 提供代码示例或用户请求示例，AI 需要知道具体怎么做   |
| **决策逻辑**           | 推荐 | 复杂任务提供条件判断或决策树，帮助 AI 做出正确选择  |
| **输出格式**           | 必须 | 明确说明 skill 应该输出什么内容                     |
| **错误处理**           | 推荐 | 说明异常情况和边界处理                              |
| **避免长段落**         | 推荐 | 超过 500 字符的段落难以提取关键信息，使用列表或表格 |
| **文件引用说明**       | 必须 | 引用的文件必须有 Markdown 链接说明                  |

**优化技巧：**

- 想象你是 AI，阅读 skill 后能否知道：什么时候用？怎么用？输出什么？
- 使用具体而非抽象的词汇
- 提供明确的操作步骤而非模糊的指导
- 为复杂场景提供决策流程

## Agent Skills 规范要点

### 目录结构

```
skill-name/
├── SKILL.md          # 必需：技能文档
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源
```

**不应包含的文件：** README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等辅助文档。

### SKILL.md 格式

**必需的前置元数据：**

```yaml
---
name: skill-name
description: 功能描述。何时使用：当用户说/需要/遇到...时
---
```

### name 字段规则

- 1-64 字符，只能包含小写字母、数字和连字符
- 不能以连字符开头或结尾，不能包含连续连字符 `--`
- 必须与父目录名匹配

### description 字段规则

- 1-1024 字符
- **必须包含两部分内容，用 `何时使用：` 分隔：**
  1. **功能描述** - 这个 skill 是做什么的
  2. **何时使用** - 用户说什么话时触发这个 skill
- **所有触发条件信息都应放在 description 中** - 不要放在正文

**好的示例：**

```yaml
description: 分析并优化其他 Skill 的文档质量问题，包括 frontmatter 格式、渐进式披露结构等检查。何时使用：当用户说"优化这个 skill"、"检查 skill 质量"、"review skill"时。
```

**不好的示例：**

```yaml
# ❌ 缺少"何时使用"部分
description: 分析并优化 Skill 的文档质量问题

# ❌ 使用"触发条件"而非"何时使用"
description: 分析 Skill 质量问题。触发条件：用户说优化 skill 时
```

## 渐进式披露设计

Skills 使用三级加载系统高效管理上下文：

1. **元数据**（name + description）- 始终在上下文中（约 100 词）
2. **SKILL.md 正文** - skill 触发时加载（建议 < 5000 词，< 500 行）
3. **捆绑资源** - AI 按需加载

**关键原则：** 当 skill 支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流程和选择指导。将变体特定的细节移到单独的参考文件中。

### 渐进式披露模式

**模式 1：高级指南 + 参考**

```markdown
## 快速开始

[核心代码示例]

## 高级功能

- **表单填写**：参见 [FORMS.md](references/FORMS.md) 完整指南
- **API 参考**：参见 [REFERENCE.md](references/REFERENCE.md)
```

**模式 2：按领域组织**

```
skill-name/
├── SKILL.md (概览和导航)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md
```

**重要指南：**

- 避免深层嵌套引用，保持引用文件在 SKILL.md 的一级子目录内
- 避免重复：信息应该只在 SKILL.md 或参考文件中存在，不要两者都有

## SKILL.md 结构模式

选择最适合 skill 目的的结构：

| 模式             | 适用场景   | 结构                                             |
| ---------------- | ---------- | ------------------------------------------------ |
| **基于工作流程** | 顺序流程   | `## 概览` → `## 工作流程决策树` → `## 步骤 1`... |
| **基于任务**     | 工具集合   | `## 概览` → `## 快速开始` → `## 任务类别 1`...   |
| **参考/指南**    | 标准或规范 | `## 概览` → `## 指南` → `## 规范`                |
| **基于能力**     | 集成系统   | `## 概览` → `## 核心能力` → `### 1. 功能`...     |

模式可以混合搭配。

## Skill 创建流程

按顺序执行以下步骤：

### Skill 创建流程

按顺序执行以下步骤：

| 步骤 | 执行动作          | 具体命令/操作                                                                                |
| ---- | ----------------- | -------------------------------------------------------------------------------------------- |
| 1    | 询问功能需求      | 运行 `AskUserQuestion` 询问 skill 功能、使用示例、触发条件                                   |
| 2    | 规划可复用资源    | 分析需求，确定需要的 scripts、references、assets                                             |
| 3    | 初始化 Skill 目录 | 运行 `RunCommand` 执行 `python scripts/init_skill.py <skill-name> --path <output-directory>` |
| 4    | 读取 SKILL.md     | 运行 `Read` 读取生成的 `.trae/skills/{skill-name}/SKILL.md`                                  |
| 5    | 编辑功能描述      | 运行 `SearchReplace` 填写 description、触发条件、执行步骤                                    |
| 6    | 创建脚本          | 如需脚本，运行 `Write` 创建到 `scripts/` 目录                                                |
| 7    | 创建参考文档      | 如需参考文档，运行 `Write` 创建到 `references/` 目录                                         |
| 8    | 验证结构          | 运行 `RunCommand` 执行 `python scripts/quick_validate.py <skill-directory>`                  |
| 9    | 测试迭代          | 根据验证结果，运行 `SearchReplace` 修复问题                                                  |

## 工作流程模式

详细的工作流程模式（顺序、条件、决策树、循环、错误处理）参见 [工作流程模式文档](references/workflows.md)。

## 输出模式

详细的输出模式（模板、示例、检查清单）参见 [输出模式文档](references/output-patterns.md)。

## 捆绑资源

### scripts/

可执行代码（Python/Bash/等）用于需要确定性可靠性或重复重写的任务。

- **何时包含**：相同的代码被重复重写或需要确定性可靠性时
- **好处**：Token 高效、确定性、可以在不加载到上下文的情况下执行
- **AI 友好原则**：代码的输入和输出应当是对 AI 友好的
  - 输入：支持命令行参数、环境变量或结构化数据（JSON/YAML），避免交互式提示
  - 输出：使用结构化格式（JSON/YAML/表格），包含明确的字段名，避免需要解析的自然语言描述
  - 错误处理：返回标准退出码，错误信息输出到 stderr，成功结果输出到 stdout

### references/

文档和参考材料，旨在根据需要加载到上下文中。

- **何时包含**：AI 工作时应该参考的详细文档
- **好处**：保持 SKILL.md 精简，只在需要时加载

### assets/

不打算加载到上下文中，而是在 AI 产生的输出中使用的文件。

- **何时包含**：skill 需要在最终输出中使用的文件（模板、图片等）
- **好处**：将输出资源与文档分离

## 实用脚本

| 脚本                                             | 用途           | 命令                                                            |
| ------------------------------------------------ | -------------- | --------------------------------------------------------------- |
| [init_skill.py](scripts/init_skill.py)           | 初始化新 skill | `python scripts/init_skill.py <skill-name> --path <output-dir>` |
| [skill_templates.py](scripts/skill_templates.py) | 模板定义模块   | 被 init_skill.py 调用，包含 SKILL.md 和示例文件模板             |
| [quick_validate.py](scripts/quick_validate.py)   | 快速验证       | `python scripts/quick_validate.py <skill-directory>`            |
| [create-skill.py](scripts/create-skill.py)       | 创建完整 skill | `python scripts/create-skill.py <skill-name>`                   |

## 创建示例

**用户输入：** "创建一个处理 PDF 的 skill"

**执行步骤：**

| 步骤 | 执行动作      | 具体命令/操作                                                                          |
| ---- | ------------- | -------------------------------------------------------------------------------------- |
| 1    | 询问场景      | 运行 `AskUserQuestion` 询问具体使用场景（提取文本、填写表单、合并等）                  |
| 2    | 规划内容      | 分析需求，确定需要 Python 脚本处理 PDF                                                 |
| 3    | 初始化目录    | 运行 `RunCommand` 执行 `python scripts/init_skill.py pdf-processor --path ./skills`    |
| 4    | 读取 SKILL.md | 运行 `Read` 读取 `./skills/pdf-processor/SKILL.md`                                     |
| 5    | 编辑描述      | 运行 `SearchReplace` 填写 description 为"处理 PDF 文件。何时使用：当用户说处理 PDF 时" |
| 6    | 创建处理脚本  | 运行 `Write` 创建 `scripts/pdf_extractor.py`                                           |
| 7    | 验证结构      | 运行 `RunCommand` 执行 `python scripts/quick_validate.py ./skills/pdf-processor`       |