Skill Creator

如何使用这个 Skill

功能概述

本 skill 用于创建符合 Agent Skills 规范的新 skill，帮助用户快速搭建 skill 框架，包括：

• 初始化 skill 目录结构（SKILL.md、scripts/、references/、assets/）
• 生成符合规范的 SKILL.md 模板文件
• 验证 skill 结构是否符合 Agent Skills 规范

使用流程

创建新 Skill 的完整流程：

1. 理解需求

   • 与用户沟通，了解 skill 的具体功能
   • 确定使用场景和触发条件
   • 询问是否需要脚本、参考文档等资源

2. 初始化 Skill 目录

   python scripts/init_skill.py <skill-name> --path <output-dir>

   示例：

   python scripts/init_skill.py pdf-processor --path ./skills

3. 编辑完善

   • 编辑生成的 SKILL.md，填写具体功能描述
   • 根据需求修改或删除示例脚本
   • 添加实际需要的参考文档

4. 验证结构

   python scripts/quick_validate.py <skill-directory>

输出结果

成功时：

• 创建完整的 skill 目录结构
• 生成包含模板内容的 SKILL.md
• 创建示例脚本和参考文档

失败时：

• 返回具体错误信息
• 说明失败原因（如目录已存在、权限不足等）
• 提供解决建议

核心原则

简洁至上 (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 格式

必需的前置元数据：

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

name 字段规则

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

description 字段规则

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

好的示例：

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

不好的示例：

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

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

渐进式披露设计

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

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

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

渐进式披露模式

模式 1：高级指南 + 参考

## 快速开始

[核心代码示例]

## 高级功能

- **表单填写**：参见 [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 创建流程

按顺序执行以下步骤：

步骤 1：用具体例子理解 Skill

通过以下问题理解具体使用示例：

• "这个 skill 应该支持什么功能？"
• "你能给出一些这个 skill 如何使用的例子吗？"
• "用户会说什么来触发这个 skill？"

步骤 2：规划可复用的 Skill 内容

分析每个例子，识别哪些脚本、参考和资产在重复执行时会有帮助。

步骤 3：初始化 Skill

运行 init_skill.py 脚本生成模板：

python scripts/init_skill.py <skill-name> --path <output-directory>

步骤 4：编辑 Skill

从步骤 2 识别的可复用资源开始实现。

编写指南： 始终使用祈使/不定式形式。前置元数据只包含 name 和 description。

添加的脚本必须通过实际运行测试。删除任何不需要的示例文件和目录。

步骤 5：迭代

测试 skill 后，根据使用反馈改进 SKILL.md 或捆绑资源。

工作流程模式

详细的工作流程模式（顺序、条件、决策树、循环、错误处理）参见 工作流程模式文档。

输出模式

详细的输出模式（模板、示例、检查清单）参见 输出模式文档。

捆绑资源

scripts/

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

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

references/

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

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

assets/

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

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

实用脚本

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

创建示例

用户需求： "创建一个处理 PDF 的 skill"

执行步骤：

1. 理解需求：询问具体使用场景（提取文本、填写表单、合并等）

2. 规划内容：确定需要哪些脚本和参考文档

3. 初始化：

python scripts/init_skill.py pdf-processor --path ./skills

4. 编辑 SKILL.md：填写模板中的 TODO 项，添加具体指令