一个 Skill 本质上是一个文件夹，核心文件是 SKILL.md。SKILL.md 负责告诉 Agent “什么时候用、怎么做”，其他目录则按需存放参考资料、脚本、模板和界面信息。
之前讲了小白怎么在 ChatGPT/Codex 中找到、安装和调用 Skill。这一篇继续往下拆：当你真的打开一个 Skill 文件夹时，里面到底应该有哪些东西？
先看一个最小 Skill
最小可用的 Skill，可以只有一个文件：
| forum-post-checker/ | └── SKILL.md |
|---|
只要这个 SKILL.md 写得规范，它就已经是一个完整 Skill。
不要一上来就追求复杂目录。对小白和新创作者来说，先把一个 SKILL.md 写清楚，比塞一堆脚本和资料更重要。
一个完整 Skill 常见长这样
更完整的 Skill 文件夹，通常会包含这些部分：
| forum-post-checker/ | ├── SKILL.md # 必需：元数据 + 核心执行说明 | ├── references/ # 可选：较长的规则、资料、案例、字段说明 | │ ├── aihelpu-style.md | │ └── publish-checklist.md | ├── scripts/ # 可选：可重复执行的脚本 | │ └── check_markdown.py | ├── assets/ # 可选：模板、图片、示例文件、字体等输出素材 | │ └── post-template.md | └── agents/ # 可选：面向界面展示的元信息 | └── openai.yaml |
|---|
不是每个 Skill 都需要这些目录。它们的作用不同，是否需要，取决于这个 Skill 要解决的问题。
SKILL.md：Skill 的核心文件
SKILL.md 是每个 Skill 必须有的文件。它通常分成两块：
- 上方的 YAML frontmatter：写 `name` 和 `description`。
- 下方的 Markdown 正文：写具体流程、规则、输出格式和注意事项。
一个最小示例：
| name: forum-post-checker | description: 检查 AIHELPU 论坛帖子发布格式。用户要求检查标题、分类、标签、母帖回链、参考资料或 Markdown 排版时使用。 | 检查用户提供的论坛帖子，并按以下顺序输出： | 1. 标题是否清楚； | 2. 分类和标签是否合适； | 3. 是否包含母帖回链； | 4. 是否有参考资料； | 5. 是否可以直接发布； | 6. 需要修改的地方。 |
|---|
这里最容易被低估的是 description。
很多人写成：
| description: 论坛助手 |
|---|
这太宽泛，Agent 不知道什么时候该用。
更好的写法是：
| description: 检查 AIHELPU 论坛帖子发布格式。用户要求检查标题、分类、标签、母帖回链、参考资料或 Markdown 排版时使用。 |
|---|
好的 description 要像触发条件，而不是广告语。
SKILL.md 正文应该写什么
正文不要写成说明书百科，而要写 Agent 执行任务时真正需要的信息。
建议包含五类内容：
| 1. 适用场景：这个 Skill 解决什么任务 | 2. 输入要求：用户需要提供什么材料 | 3. 执行步骤：Agent 按什么顺序处理 | 4. 输出格式：最后要交付什么样的结果 | 5. 停止条件：遇到哪些风险时不要继续猜 |
|---|
比如：
| ## Workflow | 1. 先判断用户提供的是草稿、链接还是完整 Markdown。 | 2. 检查标题是否能让读者一眼看懂主题。 | 3. 检查是否适合 Skill 工坊分类。 | 4. 检查是否有母帖回链和上下篇索引。 | 5. 检查是否有来源链接、版权风险或夸大表达。 | 6. 输出修改建议和可直接发布版本。 | ## Stop conditions | - 如果用户没有提供正文，先询问，不要编造。 | - 如果引用来源不清楚，标记“待补充来源”。 | - 如果内容涉及凭据、隐私或账号信息，提醒删除后再发布。 |
|---|
一句话：SKILL.md 只放“每次都会用到的核心流程”。
references/：放长资料，不要塞进主文件
references/ 用来放较长的参考资料，比如：
- 品牌风格规范
- 发布规则
- 字段说明
- API 文档摘要
- 业务知识
- 常见案例
- 审核清单
例如：
| forum-post-checker/ | ├── SKILL.md | └── references/ | ├── aihelpu-style.md | ├── skill-post-rules.md | └── title-examples.md |
|---|
如果把所有资料都塞进 SKILL.md，这个 Skill 会变得很长。Agent 一旦加载它，整段内容都会进入上下文，既浪费空间，也容易分散注意力。
更好的做法是在 SKILL.md 里写清楚什么时候读取哪个 reference：
| 当用户要求检查 AIHELPU 论坛语气时，读取 references/aihelpu-style.md。 | 当用户要求判断 Skill 工坊内容是否合规时，读取 references/skill-post-rules.md。 | 当用户要求改标题时，读取 references/title-examples.md。 |
|---|
注意：reference 文件最好从 SKILL.md 直接链接，不要层层嵌套。这样 Agent 更容易在需要时读到完整资料。
scripts/：放确定性任务
scripts/ 用来放可执行脚本。
什么时候该用脚本？判断标准很简单：如果一个步骤每次都应该得到同样答案，就适合写成脚本。
适合放进 scripts/ 的任务包括：
| 统计 Markdown 字数 | 检查链接是否为空 | 检查 frontmatter 是否完整 | 读取 CSV 并计算总数 | 批量重命名文件 | 转换图片尺寸 | 校验 JSON 格式 |
|---|
不适合放进脚本的任务包括：
| 判断标题是否吸引人 | 判断内容是否适合小白 | 判断语气是否符合社区风格 | 判断哪些段落应该删改 |
|---|
这些需要编辑判断、语气判断、业务判断，更适合写在 SKILL.md 里。
一个简单结构：
| markdown-audit/ | ├── SKILL.md | └── scripts/ | └── check_markdown.py |
|---|
SKILL.md 可以这样写：
| 当用户要求检查 Markdown 发布格式时，先运行 scripts/check_markdown.py。 | 脚本输出后： | 1. 解释错误原因； | 2. 给出修改建议； | 3. 不要自动删除用户内容； | 4. 输出可发布版本前先列出变更点。 |
|---|
脚本负责“算得准”，Skill 负责“解释得对”。
assets/：放模板和素材
assets/ 用来放最终输出可能会用到的文件。
常见内容包括：
- Word 模板
- PPT 模板
- Markdown 模板
- 图片素材
- Logo
- 字体
- 示例表格
- 前端 starter 文件
例如一个论坛发布 Skill：
| forum-post-writer/ | ├── SKILL.md | └── assets/ | ├── post-template.md | └── cover-template.png |
|---|
什么时候放 assets/？
如果这个文件是“产出时要复制、修改或作为模板使用”的，就放 assets/。
如果这个文件只是“让 Agent 阅读学习”的，就放 references/。
区分一句话：
| references/ 给 Agent 看 | assets/ 给最终产物用 |
|---|
agents/openai.yaml：给界面展示用
有些 Skill 会带一个 agents/openai.yaml。
它通常不是核心执行逻辑，而是给界面展示用的元信息，比如：
- 显示名称
- 简短说明
- 默认提示语
- 图标或品牌色
示例结构：
| forum-post-checker/ | ├── SKILL.md | └── agents/ | └── openai.yaml |
|---|
对小白来说，这个文件可以先不用管。
对创作者来说，如果你希望 Skill 在列表里展示得更清楚，可以维护它。但要注意：openai.yaml 应该和 SKILL.md 保持一致，不能一个说“论坛发帖检查”，另一个写“万能写作助手”。
不建议放什么
Skill 文件夹不是项目资料仓库。
不建议随手塞这些文件：
| README.md | INSTALLATION_GUIDE.md | QUICK_REFERENCE.md | CHANGELOG.md | 随手复制的网页全文 | 没有来源的资料包 | 和任务无关的截图 | 无说明的可执行文件 |
|---|
这些内容可能对人类有用，但不一定对 Agent 有用。Skill 的目标不是“显得很完整”，而是让 Agent 在正确时机高效执行任务。
如果确实需要给人看的说明，可以放到论坛帖子里，而不是塞进 Skill 文件夹。
Skill 的加载顺序：为什么要这样拆
Skills 使用的是“渐进式披露”思路。
可以简单理解成三层：
| 第一层：name + description | Agent 平时只看这些，用来判断要不要调用 Skill。 | 第二层：SKILL.md 正文 | 当 Skill 被选中时，Agent 才读取具体流程。 | 第三层：references / scripts / assets | 只有执行中真的需要时，Agent 才读取资料、运行脚本或使用模板。 |
|---|
所以目录结构不是为了好看，而是为了减少上下文浪费。
SKILL.md 越短越清楚，Agent 越容易抓住核心流程。
详细资料放到 references/，确定性任务放到 scripts/，输出模板放到 assets/，整个 Skill 才会更稳。
小白从哪个结构开始
如果你第一次做 Skill，不要从完整结构开始。
建议从这个结构开始：
| my-first-skill/ | └── SKILL.md |
|---|
当你发现 SKILL.md 变长，再拆：
| my-first-skill/ | ├── SKILL.md | └── references/ | └── examples.md |
|---|
当你发现有些步骤每次都要重复计算，再加：
| my-first-skill/ | ├── SKILL.md | ├── references/ | │ └── examples.md | └── scripts/ | └── check.py |
|---|
当你发现最终产物需要固定模板，再加：
| my-first-skill/ | ├── SKILL.md | ├── references/ | │ └── examples.md | ├── scripts/ | │ └── check.py | └── assets/ | └── template.md |
|---|
先能用，再变复杂。
创作者发布 Skill 内容前的自查
如果你准备在 Skill 工坊发布一个 Skill，至少检查这 8 件事：
| 1. 文件夹名称是否清楚，是否使用小写字母、数字和连字符 | 2. 是否有 SKILL.md | 3. SKILL.md 是否包含 name 和 description | 4. description 是否写清楚触发场景 | 5. 正文是否包含执行步骤和输出格式 | 6. 长资料是否放进 references/ | 7. 可重复计算是否放进 scripts/ | 8. 模板素材是否放进 assets/ |
|---|
再加一条安全检查：
| 不要把 API Key、Token、Cookie、账号密码、客户资料、内部文件放进 Skill 文件夹。 |
|---|
Skill 可能会被分享、提交或安装到不同环境里，敏感信息必须留在外部配置中。
一个 Skill 工坊示例结构
假设我们要做一个 AIHELPU 论坛发帖检查 Skill，可以这样设计：
| aihelpu-post-checker/ | ├── SKILL.md | ├── references/ | │ ├── aihelpu-style.md | │ ├── skill-section-rules.md | │ └── title-examples.md | ├── scripts/ | │ └── count_markdown_stats.py | └── assets/ | └── post-template.md |
|---|
分工是：
| SKILL.md：写触发条件、检查流程、输出格式 | references/aihelpu-style.md：写论坛语气和内容风格 | references/skill-section-rules.md：写 Skill 工坊发布规范 | references/title-examples.md：放标题案例 | scripts/count_markdown_stats.py：统计字数、标题数、链接数 | assets/post-template.md：给最终发布稿套模板 |
|---|
这样一来，Agent 既知道怎么做，也不会一次性读进所有资料。
小结
一个 Skill 文件夹不是越大越好。
SKILL.md 是必需的，负责定义 Skill 的名称、触发条件和核心流程。
references/ 用来放长资料，避免主文件膨胀。
scripts/ 用来处理确定性任务，让结果更稳定。
assets/ 用来放模板和最终产物需要的素材。
agents/openai.yaml 主要服务界面展示，小白可以先不管。
对新手来说，最好的起点永远是：
| 一个文件夹 | 一个 SKILL.md | 一个明确场景 | 一套可检查流程 |
|---|