| name | skill_creator |
| description | 创建或更新 VOTX Agent Skill 的指导技能。用于设计 SKILL.md、工具型或指令型 Skill、scripts/references/assets 资源、触发描述、渐进式披露结构，以及验证现有 Skill 是否适配框架。 |
Skill Creator
设计、创建、更新和审查 VOTX Agent Skill。Skill 是包含 SKILL.md 及可选资源的独立能力包。
插件路径
plugins/skill_creator/
Skill 类型
| 类型 | 结构 | 用途 |
|---|
| 工具型 | SKILL.md + tool.py | 注册可直接 function call 的工具 |
| 指令型 | SKILL.md | 注入领域流程、规范和知识导航 |
标准目录
skill-name/
├── SKILL.md # 必需
├── tool.py # 工具型 Skill 可选/常用
├── scripts/ # 可重复执行的确定性脚本
├── references/ # 按需读取的详细文档
└── assets/ # 模板、图片、字体等输出资源
不要创建无必要的 README、安装指南、更新日志等重复文档。
SKILL.md 最小格式
---
name: skill_name
description: 说明能力、适用场景和触发条件。
---
# Skill 标题
核心流程与必要约束。
框架主要依赖 frontmatter 的 name 和 description 判断是否触发，因此描述必须包含“做什么”和“何时使用”。
VOTX 推荐正文结构
根据复杂度选用以下章节，不要求机械堆满：
- Skill 标题与目标
- 插件相对路径
- 注册工具及用途（工具型）
- 参数、默认值和厂商差异
- 结果格式与 artifact
- 前置条件和配置
- 标准工作流
- 常见规范
- 常见处理办法
- 常见教训与限制
- references/scripts/assets 导航
创建与更新流程
- 理解使用场景：收集会触发 Skill 的用户表达和具体任务。
- 选择类型：决定是工具型还是指令型，避免把纯流程硬做成工具。
- 规划资源：重复且确定的操作放 scripts；详细资料放 references；模板素材放 assets。
- 读取现有实现：更新已有 Skill 时，先读
SKILL.md、tool.py 和相邻插件风格。
- 编写说明：保持正文精炼，复杂细节通过 references 渐进披露。
- 实现工具：工具 schema 的 description 写清触发场景；参数说明与真实 handler 一致。
- 验证：Python 工具执行
python -m py_compile <tool.py>；检查 SKILL.md 路径、工具名和参数是否一致。
- 迭代：根据真实调用中的误触发、漏触发、参数错误继续调整。
工具型 Skill 注册规范
- 使用
register_tool(schema, handler) 注册。
- schema 中工具名必须与 handler 映射一致。
description 写明能力和典型触发词，避免只写内部实现。required 只保留真正必需的参数。- 厂商差异较大的参数（音色、格式、尺寸等）优先使用自由字符串并在 description 中给示例；框架内部协议值可保留 enum。
- 工具结果优先返回结构化 JSON；文件结果通过 artifact 暴露给前端。
- 异常返回
ERROR: 文本，不泄露堆栈和密钥。
渐进式披露
- frontmatter 元数据始终在上下文中。
- SKILL.md 正文仅在触发后加载。
- 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 保持一致，过期参数说明会直接误导调用。
- 不要为展示完整而堆砌常识；只保留模型执行任务时真正需要的信息。
- 新增脚本必须实际运行验证，不能只写不测。
