steelan9199/skill-creator-yashu

🎯 触发映射

| 用户输入触发词 | 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 格式

必需的前置元数据：

---
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 创建流程

按顺序执行以下步骤：

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 修复问题 |

工作流程模式

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

输出模式

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

捆绑资源

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 | 询问场景 | 运行 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 |