说明：这里说的“训练 Skill”，并不是重新训练大模型参数，而是为 Codex 编写一个可复用的专业工作流。更准确的说法是：创建、调试和迭代 Codex Skill。

一、什么是 Codex Skill

Codex Skill 可以理解为给 Codex 准备的一份“专业上岗手册”。

普通对话里，我们每次都要反复告诉 Codex：

• 这个任务应该按什么流程做；
• 哪些文件需要优先读取；
• 哪些命令可以直接运行；
• 哪些坑不能踩；
• 输出格式应该长什么样；
• 项目里有哪些固定规范。

Skill 的作用，就是把这些重复说明沉淀成一个独立目录。之后只要用户的任务命中这个 Skill，Codex 就会自动加载对应说明，按你设定的流程工作。

它不是模型训练，也不需要准备数据集、GPU 或微调流程。Skill 更像是：

可复用提示词 + 操作流程 + 脚本工具 + 参考资料 + 模板资源

二、Skill 适合解决什么问题

适合写成 Skill 的任务，一般有下面几个特点：

• 经常重复做；
• 流程比较固定；
• 有明确的输入和输出；
• 需要特定领域知识；
• 需要固定脚本、模板或参考资料；
• 普通提示词容易漏步骤。

比如：

• 自动生成 CSDN 技术文章；
• 按公司规范写接口文档；
• 处理固定格式的 Excel 报表；
• 根据论文模板排版 LaTeX；
• 调用某个内部 API；
• 生成固定风格的 PPT；
• 按团队规范做代码 Review；
• 自动整理会议纪要。

不适合写成 Skill 的任务：

• 一次性很强的临时需求；
• 没有稳定流程的开放闲聊；
• 只需要一句提示词就能完成的小任务；
• 需要 Codex 永久记住个人隐私信息的场景。

三、Skill 的基本目录结构

一个标准 Skill 通常长这样：

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── helper.py
├── references/
│   └── guide.md
└── assets/
    └── template.md

其中只有 SKILL.md 是必须的，其他目录按需添加。

路径	作用
SKILL.md	Skill 的核心说明文件，必须存在
agents/openai.yaml	面向界面的展示信息，推荐保留
scripts/	可执行脚本，适合放稳定、重复、容易写错的逻辑
references/	参考资料，适合放较长文档、规范、API 说明
assets/	模板、图片、字体、样例文件等输出素材

四、最重要的文件：SKILL.md

SKILL.md 分为两部分：

1. YAML frontmatter；
2. Markdown 正文说明。

最小示例：

---
name: csdn-writer
description: Generate Chinese CSDN-ready Markdown technical articles with clear structure, practical examples, SEO-friendly titles, code blocks, summaries, and publishing-ready formatting. Use when the user asks to write, polish, or structure a technical article for CSDN.
---

# CSDN Writer

Write in Simplified Chinese by default.

## Workflow

1. Clarify the target reader and topic.
2. Build an outline before drafting.
3. Use practical examples and reproducible commands.
4. Keep headings suitable for CSDN publishing.
5. End with a concise summary and checklist when useful.

## Output

Create a complete Markdown article.
Use fenced code blocks with language tags.
Avoid empty marketing language.

1. name

name 是 Skill 的唯一名称，建议使用小写字母、数字和短横线。

推荐：

csdn-writer
pdf-editor
latex-paper-formatting
gh-address-comments

不推荐：

CSDN Writer
我的技能
skill_for_everything

命名建议：

• 使用短横线；
• 不要太长；
• 最好动词或任务导向；
• 一个 Skill 只做一类事情。

2. description

description 是触发 Skill 的关键。Codex 会根据它判断什么时候该使用这个 Skill。

写 description 时要包括两类信息：

• 这个 Skill 能做什么；
• 用户说什么时应该触发它。

示例：

description: Create, polish, and format Chinese CSDN-ready Markdown articles for programming, software installation, debugging, AI tools, and engineering tutorials. Use when the user asks to write a CSDN article, generate a Markdown blog post, polish a technical article, or turn notes into a publishable tutorial.

常见错误是只写：

description: Write articles.

这太短了，Codex 不容易判断何时使用。

另一个常见错误是把触发条件写在正文里。正文只有在 Skill 已经触发后才会被加载，所以“什么时候使用这个 Skill”一定要写进 description。

五、Skill 正文应该怎么写

SKILL.md 正文不是越长越好。Codex 本身已经很聪明，不需要在 Skill 里解释常识。

好的 Skill 正文应该写：

• 任务流程；
• 必须遵守的约束；
• 项目特有规范；
• 资源文件该怎么用；
• 常见失败场景；
• 输出格式要求；
• 需要运行的验证命令。

不建议写：

• 大段背景科普；
• 和任务无关的说明；
• 已经众所周知的基础知识；
• 重复的提示词；
• 过长的教程全文。

一个更实用的正文结构：

# Skill Name

## Workflow

1. Inspect the input files.
2. Choose the correct template from assets/.
3. Generate the output.
4. Run validation.
5. Report the saved file path.

## Resources

- Use references/style-guide.md when writing article copy.
- Use assets/article-template.md as the default Markdown skeleton.
- Use scripts/check_markdown.py before final delivery.

## Rules

- Write in Simplified Chinese unless the user requests another language.
- Do not invent citations.
- Keep code examples runnable.

六、什么时候需要 scripts、references、assets

1. scripts：把容易写错的步骤固化

如果某段代码会被 Codex 反复重写，或者这段逻辑要求稳定可靠，就适合放到 scripts/。

例子：

scripts/
├── check_markdown.py
├── render_docx.py
└── convert_csv.py

适合放脚本的场景：

• 转换文件格式；
• 校验 Markdown；
• 调用固定 API；
• 批量处理图片；
• 生成目录结构；
• 解析复杂数据。

脚本的好处是：可执行、可测试、结果稳定，还能减少上下文占用。

2. references：放详细资料

如果某些资料很长，但不是每次都要读，就放进 references/。

例子：

references/
├── company-style-guide.md
├── api-schema.md
├── database-tables.md
└── article-examples.md

SKILL.md 里只写什么时候读取它：

Use references/company-style-guide.md when the user asks for public-facing copy.
Use references/api-schema.md when generating API examples.

这样 Codex 只有在需要时才加载对应资料，不会每次都把所有内容塞进上下文。

3. assets：放模板和素材

assets/ 适合放最终产物会用到的文件。

例子：

assets/
├── article-template.md
├── report-template.docx
├── logo.png
└── ppt-theme.pptx

如果你的任务需要固定模板，放在 assets/ 会比每次让 Codex 重新生成更稳。

七、创建 Skill 的推荐流程

第一步：明确使用场景

先写出 3 到 5 个真实用户请求。

例如你要做一个 CSDN 写作 Skill：

帮我写一篇适合 CSDN 发布的 Docker 安装教程
把这份 Word 安装说明整理成 CSDN Markdown
根据这个 B 站视频写一篇排错文章
润色这篇技术博客，让它更适合 CSDN

这些例子会决定 Skill 的触发描述、工作流和资源设计。

第二步：规划资源

分析这些任务需要什么复用内容：

需要文章模板 -> assets/article-template.md
需要风格规范 -> references/csdn-style.md
需要 Markdown 检查 -> scripts/check_markdown.py

不要一开始就创建一堆目录。只放真正会用到的资源。

第三步：初始化 Skill

如果有初始化脚本，可以用类似命令创建模板：

scripts/init_skill.py csdn-writer --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources scripts,references,assets

Windows PowerShell 可以写成：

python .\scripts\init_skill.py csdn-writer --path "$env:USERPROFILE\.codex\skills" --resources scripts,references,assets

如果没有初始化脚本，也可以手动创建目录，但要确保至少包含：

csdn-writer/
└── SKILL.md

第四步：编写 SKILL.md

重点写三部分：

• description：让 Codex 知道何时触发；
• Workflow：让 Codex 知道怎么做；
• Resources：让 Codex 知道什么时候用哪些脚本、参考资料和模板。

不要把 SKILL.md 写成完整教材。它是给 Codex 执行任务用的，不是给人阅读入门用的。

第五步：校验 Skill

如果有校验脚本，运行：

scripts/quick_validate.py /path/to/csdn-writer

校验重点包括：

• YAML frontmatter 格式是否正确；
• 是否包含 name；
• 是否包含 description；
• 名称是否符合规范；
• 文件结构是否合理。

第六步：真实任务测试

不要只看 Skill 写得漂不漂亮，要用真实任务测试。

例如：

使用 csdn-writer，帮我把某个软件安装说明写成 CSDN Markdown
使用 csdn-writer，根据一段报错日志写一篇排错文章
使用 csdn-writer，润色一篇已经写好的技术文章

观察 Codex 是否：

• 正确触发 Skill；
• 按流程执行；
• 会读取正确的 reference；
• 会使用正确的 template；
• 输出格式符合预期；
• 没有漏掉验证步骤。

如果测试时发现问题，就回到 SKILL.md 或资源文件里修改。

八、完整示例：训练一个 CSDN 写作 Skill

下面是一个可参考的 SKILL.md：

---
name: csdn-writer
description: Create, polish, and format Simplified Chinese CSDN-ready Markdown technical articles for software installation, debugging, programming tutorials, AI tools, and engineering notes. Use when the user asks to write a CSDN article, generate a Markdown blog post, convert notes into a publishable tutorial, or polish technical content for CSDN.
---

# CSDN Writer

## Workflow

1. Identify the topic, target reader, and source material.
2. Extract concrete facts from provided files, links, screenshots, logs, or notes.
3. Build a practical article outline before drafting.
4. Write a complete Markdown article with clear headings.
5. Add code blocks, commands, screenshots placeholders, and checklists when useful.
6. Save the final article as a `.md` file when working in a local workspace.

## Style

- Write in Simplified Chinese by default.
- Use a practical tutorial tone.
- Prefer short paragraphs and clear numbered steps.
- Avoid empty marketing copy.
- Do not invent facts, versions, commands, links, or citations.

## Structure

Use this structure unless the task suggests a better one:

1. Title
2. Problem background
3. Environment or prerequisites
4. Step-by-step solution
5. Common errors
6. Summary

## Resources

- Use references/csdn-style.md when polishing article style.
- Use assets/article-template.md when the user asks for a standard article template.
- Use scripts/check_markdown.py before final delivery if it exists.

这个 Skill 的重点是：

• description 明确写了 CSDN、Markdown、技术文章、安装教程、排错文章等触发词；
• Workflow 规定了从提取事实到保存文件的流程；
• Style 限制了输出风格；
• Resources 告诉 Codex 何时加载其他文件。

九、Skill 迭代技巧

1. 从真实失败案例中改

不要凭空优化 Skill。最有效的改法是记录真实失败：

问题：Codex 每次都忘记保存 md 文件
修改：在 Workflow 最后增加“Save the final article as a .md file”

问题：Codex 会编造参考链接
修改：在 Style 增加“Do not invent facts, versions, commands, links, or citations”

2. 把长内容拆到 references

如果 SKILL.md 越写越长，说明它可能承担了太多内容。

可以把详细内容拆出去：

references/
├── style-guide.md
├── examples.md
└── troubleshooting.md

SKILL.md 只保留导航：

Read references/troubleshooting.md when debugging article generation quality.

3. 把稳定流程写成脚本

如果 Codex 总是在同一个地方写错，就考虑用脚本固定下来。

例如 Markdown 检查脚本可以检查：

• 是否有一级标题；
• 是否存在空链接；
• 代码块是否闭合；
• 是否包含过长行；
• 是否有重复标题。

4. 不要做万能 Skill

一个 Skill 不应该试图覆盖所有任务。

不推荐：

super-assistant

推荐拆成：

csdn-writer
pdf-reviewer
api-doc-writer
frontend-builder

Skill 越聚焦，触发越准确，执行越稳定。

十、常见问题

1. Skill 会改变模型能力吗

不会。Skill 不会修改模型参数，也不会让模型永久学习新知识。

它只是让 Codex 在合适的时候读取你写好的说明、脚本和资源。

2. 为什么我写了 Skill 但 Codex 没触发

优先检查 description。

常见原因：

• 描述太短；
• 没写触发场景；
• 没写用户可能使用的关键词；
• Skill 名称和任务关系不明显；
• Skill 没放在 Codex 能发现的位置。

3. Skill 里能放公司内部资料吗

可以，但要注意权限和敏感信息管理。

适合放：

• API 文档；
• 数据库表结构；
• 编码规范；
• 公开或内部模板；
• 非敏感业务流程。

不建议直接放：

• 密码；
• API Key；
• 私钥；
• 个人隐私；
• 未脱敏客户数据。

4. Skill 写得越详细越好吗

不是。

Skill 的关键是“刚好足够”。Codex 已经知道通用知识，你只需要补充它不知道的流程、约束、资源和项目规范。

十一、总结

训练 Codex Skill，本质上不是训练模型，而是把可重复的专业任务沉淀成一个结构化工作流。

核心步骤可以总结为：

明确真实任务
设计触发描述
编写 SKILL.md
拆分 references
固化 scripts
沉淀 assets
运行校验
用真实任务迭代

写好一个 Skill 后，Codex 不再只是“听你临时描述怎么做”，而是可以在特定领域里按照你定义的流程、规范和工具稳定执行任务。这才是 Skill 最有价值的地方。