这是本文档旧的修订版！
Skill 本质上是一个文件夹，核心文件是 SKILL.md。它的标准格式由两部分组成：
第一部分：YAML 前置元数据 文件顶部用 — 包裹，包含必需和可选字段：
yaml — name: your-skill-name # 必需：唯一标识，小写+连字符，≤64字符 description: > # 必需：功能和触发场景，≤1024字符
清晰描述这个 Skill 做什么、什么时候用。 这是 AI 判断是否调用的关键依据。
license: MIT # 可选：许可证 version: “1.0” # 可选：版本号 metadata: # 可选：扩展信息
author: YourName
— 关于命名的硬性规则：
长度 2-64 字符，只能含小写字母、数字、连字符 -
首尾不能是 -，不能有连续的 –
不能使用 admin、api、auth 等保留字
第二部分：Markdown 正文 元数据之后就是自由格式的 Markdown 指令，告诉 AI 具体怎么执行。可以参考这个结构：
markdown # Skill 名称
## 概述 说明这个 Skill 解决什么问题，核心价值是什么。
## 适用场景 / 触发条件 明确什么时候该用、什么时候不该用。 - ✅ 适用情况：… - ❌ 不适用情况：…
## 前置条件 执行前需要满足的条件。
## 处理步骤 ### Step 1: 具体动作 ### Step 2: 具体动作 ### Step 3: 具体动作
## 输入/输出示例 给出具体例子，让 AI 理解期望的结果。
## 失败处理 告诉 AI 遇到问题怎么办。 Skill 的进阶目录结构 任务变得复杂时，可以把内容拆分到不同目录，而不是全部塞进 SKILL.md：
text my-skill/ ├── SKILL.md # 必需：入口指令文件 ├── references/ # 可选：参考资料（模板、配置、术语表等） │ ├── config.yaml │ └── output-template.md ├── scripts/ # 可选：稳定动作脚本（解析、排序、去重等） │ └── data_processor.py └── assets/ # 可选：静态资源（图片、字体等）
└── template.json
每个目录的职责：
SKILL.md：只写触发条件、核心流程、边界规则
references/：放模板、配置、示例、偏好说明——AI 按需读取
scripts/：放可稳定执行的脚本——确定性动作交给代码，比让 AI 临场发挥更可靠
assets/：放图片、模板文件等静态资源
设计 Skill 的核心原则 1. 精准的 description 决定触发率 description 是 AI 判断“什么时候用这个 Skill”的唯一入口。写得越具体，触发越准。
text ❌ 差的描述：“翻译相关” ✅ 好的描述：“将中文内容翻译成英文。当用户说'翻译'、'translate'或要求把中文转成英文时使用，保留专业术语和原有的语气。” 口诀：动作 + 触发关键词 + 关键约束。
2. 把稳定动作交给脚本 下面这些事不应该让 AI 每次“临场发挥”：
解析 XML/JSON
去重、排序
读取固定格式文件
格式转换和字段校验
这些动作一旦写成脚本，每次结果一致，不会出现“这次漏一条、下次排序变了”的问题。AI 的价值在判断价值、归纳总结、风格把控这些语义层面。
3. 渐进式披露，控制 Token 成本 Skill 的加载是分层的：
层级 内容 加载时机 Level 1 name + description 始终驻留在上下文 Level 2 SKILL.md 正文 Skill 被触发时加载 Level 3 references/ + scripts/ 执行中按需读取 原则：Level 1 越精准越好，Level 2 越精简越好，Level 3 放心放（按需加载不占常驻空间）。
4. 职责单一 每个 Skill 只做一件事。把“运行测试 + 更新状态 + 发通知”塞进一个 Skill，AI 容易搞混，触发也容易错。
快速上手：5 步设计法 如果你手头有一个重复流程想做成 Skill，可以按这个步骤来：
写清楚触发场景——一句话说清什么情况下用
拆出固定流程——写成“先做什么、后做什么”的顺序步骤
把材料移到 references/——模板、配置、风格偏好别塞进 SKILL.md
把稳定动作脚本化——解析、排序、去重交给脚本
把 AI 留给真正需要判断的部分——价值判断、风格把控、归纳总结
什么时候该写 Skill？ 一个简单的判断标准：同样的规则跟 AI 纠正了 3 次以上，就该写 Skill 了。 一次性的任务直接用提示词，别折腾。
张叶安