# Skill Creator

> 创建或更新 VOTX Agent Skill 的指导技能。用于设计 SKILL.md、工具型或指令型 Skill、scripts/references/assets 资源、触发描述、渐进式披露结构，以及验证现有 Skill 是否适配框架。

- Skill: `kesepain-ke/skill-creator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add kesepain-ke/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kesepain-ke/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kesepain-ke (https://skillmd.com/u/kesepain-ke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kesepain-ke/skill-creator

---


# Skill Creator

设计、创建、更新和审查 VOTX Agent Skill。Skill 是包含 `SKILL.md` 及可选资源的独立能力包。

## 插件路径

`plugins/skill_creator/`

## Skill 类型

| 类型 | 结构 | 用途 |
|------|------|------|
| 工具型 | `SKILL.md` + `tool.py` | 注册可直接 function call 的工具 |
| 指令型 | `SKILL.md` | 注入领域流程、规范和知识导航 |

## 标准目录

```text
skill-name/
├── SKILL.md              # 必需
├── tool.py               # 工具型 Skill 可选/常用
├── scripts/              # 可重复执行的确定性脚本
├── references/           # 按需读取的详细文档
└── assets/               # 模板、图片、字体等输出资源
```

不要创建无必要的 README、安装指南、更新日志等重复文档。

## SKILL.md 最小格式

```markdown
---
name: skill_name
description: 说明能力、适用场景和触发条件。
---

# Skill 标题

核心流程与必要约束。
```

框架主要依赖 frontmatter 的 `name` 和 `description` 判断是否触发，因此描述必须包含“做什么”和“何时使用”。

## VOTX 推荐正文结构

根据复杂度选用以下章节，不要求机械堆满：

1. Skill 标题与目标
2. 插件相对路径
3. 注册工具及用途（工具型）
4. 参数、默认值和厂商差异
5. 结果格式与 artifact
6. 前置条件和配置
7. 标准工作流
8. 常见规范
9. 常见处理办法
10. 常见教训与限制
11. references/scripts/assets 导航

## 创建与更新流程

1. **理解使用场景**：收集会触发 Skill 的用户表达和具体任务。
2. **选择类型**：决定是工具型还是指令型，避免把纯流程硬做成工具。
3. **规划资源**：重复且确定的操作放 scripts；详细资料放 references；模板素材放 assets。
4. **读取现有实现**：更新已有 Skill 时，先读 `SKILL.md`、`tool.py` 和相邻插件风格。
5. **编写说明**：保持正文精炼，复杂细节通过 references 渐进披露。
6. **实现工具**：工具 schema 的 description 写清触发场景；参数说明与真实 handler 一致。
7. **验证**：Python 工具执行 `python -m py_compile <tool.py>`；检查 SKILL.md 路径、工具名和参数是否一致。
8. **迭代**：根据真实调用中的误触发、漏触发、参数错误继续调整。

## 工具型 Skill 注册规范

- 使用 `register_tool(schema, handler)` 注册。
- schema 中工具名必须与 handler 映射一致。
- `description` 写明能力和典型触发词，避免只写内部实现。
- `required` 只保留真正必需的参数。
- 厂商差异较大的参数（音色、格式、尺寸等）优先使用自由字符串并在 description 中给示例；框架内部协议值可保留 enum。
- 工具结果优先返回结构化 JSON；文件结果通过 artifact 暴露给前端。
- 异常返回 `ERROR:` 文本，不泄露堆栈和密钥。

## 渐进式披露

1. frontmatter 元数据始终在上下文中。
2. SKILL.md 正文仅在触发后加载。
3. references/scripts/assets 只在实际需要时读取或执行。

正文接近 500 行时应拆分。引用文件保持一层深度，并在 SKILL.md 中说明何时读取。

## 结果说明

本 Skill 是指令型技能，不注册工具。产出通常是：

- 新建或更新后的 Skill 目录；
- 标准化的 `SKILL.md`；
- 工具 schema/handler 设计说明；
- 验证结果与已知限制。

## 常见规范

- 能扩展现有 Skill 时不重复新建同类 Skill。
- 内置能力放 `plugins/`，用户扩展或实验能力放 `skills/`。
- Skill 名称清晰稳定，目录名建议使用小写下划线或短横线。
- references 中不要复制 SKILL.md 已有正文。

## 常见处理办法

- **工具不触发**：强化 frontmatter description 和 schema description 中的触发场景。
- **工具误触发**：明确边界、反例和优先级，例如“简单搜索不用深度研究”。
- **参数不兼容**：区分框架协议参数与厂商参数，减少不必要 enum。
- **正文过长**：把厂商表、API 文档和大量示例移入 references。
- **结果无法展示**：检查工具是否返回 `artifacts[]`。

## 常见教训

- frontmatter 描述是主要触发入口，把“何时使用”只写在正文里没有作用。
- SKILL.md 必须与实际 tool.py 保持一致，过期参数说明会直接误导调用。
- 不要为展示完整而堆砌常识；只保留模型执行任务时真正需要的信息。
- 新增脚本必须实际运行验证，不能只写不测。