🎯 触发映射

创建模式

执行步骤

输出结果

成功时输出示例：

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

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

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

失败时输出示例：

❌ Skill 创建失败

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

错误处理

核心原则

简洁至上 (Concise is Key)

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

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

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

设置适当的自由度

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

AI 友好性 (AI-Friendly)

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

优化技巧：

• 想象你是 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 目的的结构：

模式可以混合搭配。

Skill 创建流程

按顺序执行以下步骤：

Skill 创建流程

按顺序执行以下步骤：

工作流程模式

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

输出模式

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

捆绑资源

scripts/

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

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

references/

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

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

assets/

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

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

实用脚本

创建示例

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

执行步骤：