Codex Skill 入门：从 0 到 1 写一个自己的技能
平时用 Codex 或其他 AI 编程工具时，我们经常会遇到一个问题：
同一类任务，每次都要重新告诉 AI 一遍规则。比如：
- 写博客时，希望它固定使用你的文章风格；
- 改代码时，希望它固定先看项目结构，再动手；
- 处理 PDF、Excel、PPT 时，希望它按固定流程验证；
- 写后端文章时，希望它用“概念 -> 例子 -> 误区 -> 总结”的结构；
- 生成文档时，希望它遵守公司内部模板。
如果每次都靠复制粘贴提示词，很麻烦，也容易漏。
Skill 解决的就是这个问题。
简单说：
Skill 就是一份给 AI 用的专项说明书。它告诉 AI：遇到某类任务时，应该按什么流程、使用什么规则、参考哪些资料、调用哪些脚本。
它不是普通文章，也不是项目代码，而是一种可以被 Codex 自动识别和加载的能力包。
1. Skill 适合解决什么问题
Skill 适合处理“重复出现、流程固定、需要上下文规则”的任务。
比如：
| 场景 | 是否适合 Skill | 原因 |
|---|---|---|
| 每次写博客都要统一风格 | 适合 | 规则稳定，重复出现 |
| 每次生成周报都按同一模板 | 适合 | 模板固定 |
| 每次处理 Excel 都要校验公式 | 适合 | 流程固定 |
| 临时问一个 Java 问题 | 不太适合 | 一次性问题 |
| 只想让 AI 翻译一句话 | 不太适合 | 不需要长期规则 |
可以这样判断：
如果这件事以后还会经常做，而且每次做法差不多，就适合写成 Skill。2. Skill 和普通提示词的区别
普通提示词是一次性的。
比如你对 AI 说：
以后写文章时，先讲概念，再讲案例，最后讲常见误区。这句话只在当前对话里有效。换一个线程，或者过很久以后，AI 可能就忘了。
Skill 更像是固定能力。
只要它被安装并且触发，Codex 就会读取对应的 SKILL.md，按里面的流程执行。
可以理解成：
普通提示词：这次你这么做。Skill：以后遇到这类任务，你都这么做。3. 一个 Skill 的基本目录结构
一个最简单的 Skill 通常长这样：
my-blog-writer/ SKILL.md复杂一点可以这样：
my-blog-writer/ SKILL.md references/ style-guide.md examples.md scripts/ check-frontmatter.js assets/ cover-template.png每个部分的作用：
| 文件或目录 | 作用 |
|---|---|
SKILL.md | 必须有，写 Skill 的核心说明 |
references/ | 存放详细参考资料，需要时再读 |
scripts/ | 存放可重复执行的脚本 |
assets/ | 存放模板、图片、示例文件等资源 |
新手刚开始不用想太复杂。
先写一个只有 SKILL.md 的 Skill 就够了。
4. SKILL.md 的最小写法
SKILL.md 分成两部分：
YAML frontmatter正文说明最小示例：
---name: blog-writerdescription: Use when writing or polishing Chinese technical blog posts. Helps structure articles with beginner-friendly explanations, examples, common pitfalls, and summaries.---
# Blog Writer
When writing a technical blog post:
1. Start with the problem the reader has.2. Explain the concept in simple language.3. Add a realistic code or business example.4. Point out common mistakes.5. End with a short summary.
Keep the tone clear, practical, and beginner-friendly.上面最重要的是两个字段：
name: blog-writerdescription: Use when writing or polishing Chinese technical blog posts...name 是 Skill 名称。
description 是触发说明，告诉 Codex 什么时候应该使用这个 Skill。
5. name 怎么写
name 建议：
- 用英文；
- 全小写；
- 单词之间用
-； - 不要太长；
- 能看出这个 Skill 是干什么的。
推荐：
name: blog-writername: java-code-reviewername: mysql-article-helpername: weekly-report-writer不推荐：
name: 我的博客技能name: Skill1name: testname: super-awesome-ai-helper-for-everything名字不是越酷越好，而是越清楚越好。
6. description 最重要
description 不是普通简介，它决定 Skill 什么时候会被触发。
所以不要只写：
description: 写博客用这太短了，AI 不容易判断什么时候该用。
更推荐写清楚：
description: Use when writing, expanding, or polishing Chinese technical blog posts, especially Java, backend, database, AI coding, and project-practice articles. The skill helps produce beginner-friendly structure, examples, common pitfalls, and concise summaries.一个好的 description 应该包含：
- 这个 Skill 做什么；
- 什么场景下使用；
- 适合哪些任务；
- 能带来什么输出风格。
可以简单记：
description 写得越清楚，Codex 越容易在正确的时候使用它。7. 正文应该写什么
SKILL.md 正文不是写给普通用户看的，而是写给 AI 看的。
所以不要写成宣传介绍。
不要这样：
# 欢迎使用我的博客写作 Skill
这是一个非常强大的 Skill，可以帮助你提升写作效率。更应该这样：
# Blog Writer
When expanding a technical blog post:
1. Preserve the user's original topic and wording style.2. Use beginner-friendly explanations before advanced terms.3. Add practical examples from backend development.4. Avoid empty slogans.5. Keep sections ordered from basic concept to real project use.正文要写的是：
- 遇到任务后第一步做什么；
- 输出应该是什么结构；
- 有哪些限制；
- 哪些情况需要先问用户；
- 哪些资源文件需要读取；
- 怎么验证结果。
8. references 什么时候用
如果规则很多，不要全部塞进 SKILL.md。
可以把详细内容拆到 references/。
比如：
blog-writer/ SKILL.md references/ java-style.md mysql-style.md ai-coding-style.mdSKILL.md 里这样写：
## References
- For Java backend posts, read `references/java-style.md`.- For MySQL posts, read `references/mysql-style.md`.- For AI coding posts, read `references/ai-coding-style.md`.这样做的好处是：
SKILL.md不会太长；- 只有需要时才读取对应资料；
- 后期维护更清楚。
如果所有内容都堆在一个文件里，Skill 会变得很臃肿。
9. scripts 什么时候用
如果某个动作每次都要重复，而且容易写错，就适合放进 scripts/。
比如写博客时，每次都要检查 frontmatter：
title 是否存在published 是否存在tags 是否是数组category 是否存在draft 是否是 false就可以写一个脚本：
scripts/check-frontmatter.jsSkill 里告诉 Codex：
After editing posts, run:
```bashnode scripts/check-frontmatter.js <post-path>```脚本适合做确定性的事情。
比如：
- 检查文件格式；
- 生成固定模板；
- 转换文件；
- 批量校验；
- 渲染预览；
- 提取数据。
不要把所有事情都写脚本，只有重复、稳定、容易出错的步骤才值得脚本化。
10. assets 什么时候用
assets/ 用来放输出时会用到的资源。
比如：
assets/ blog-cover-template.png report-template.docx style-example.md如果 Skill 是做文档、PPT、图片、网站模板，assets/ 会很有用。
如果只是写一篇技术文章，通常不需要 assets。
11. 一个博客写作 Skill 示例
下面是一个完整的新手示例。
目录：
blog-writer/ SKILL.mdSKILL.md：
---name: blog-writerdescription: Use when writing, expanding, or polishing Chinese technical blog posts, especially Java backend, database, AI coding, and project-practice articles. Produce beginner-friendly explanations, practical examples, common pitfalls, and concise summaries.---
# Blog Writer
Write for beginner and intermediate Chinese developers.
## Writing Flow
1. Start from the practical problem.2. Explain the concept in plain language.3. Add a realistic backend example.4. Add common mistakes and how to avoid them.5. End with a short summary.
## Style
- Use clear Chinese.- Prefer short paragraphs.- Use tables when comparing options.- Use code blocks for commands, configuration, and examples.- Avoid vague motivational wording.
## Article Structure
For technical tutorials, prefer:
1. What problem this solves2. Core concept3. Basic example4. Project practice5. Common pitfalls6. Summary
## Validation
Before finishing:
1. Check that the title matches the article content.2. Check that examples are consistent.3. Check that there are no unfinished TODO placeholders.这个 Skill 很简单，但已经能用了。
12. 常见报错：category 不支持
你可能会遇到这个报错：
Attribute 'category' is not supported in skill files.Supported: argument-hint, compatibility, description, disable-model-invocation, license, metadata, name, user-invocable.这个报错的意思是：
Codex 把这个文件当成了真正的 Skill 文件，所以会按 Skill 的 frontmatter 规则校验。
注意，这里说的是 SKILL.md，不是普通博客文章。
比如在博客文章里，这样写通常没问题：
---title: "Codex Skill 入门"published: 2026-05-06tags: ["AI 编程"]category: "AI编程"draft: false---因为这是博客系统的 frontmatter。
但在真正的 SKILL.md 里，不要这样写：
---name: blog-writerdescription: Use when writing blog posts.category: AI编程---更稳的写法是：
---name: blog-writerdescription: Use when writing blog posts.---也就是说：
博客文章 frontmatter 可以有 category。Codex Skill 的 SKILL.md 不能随便写 category。如果你的文章文件名叫 skill.md，在 Windows 上还可能因为大小写不敏感，被某些工具误当成 SKILL.md。
所以写介绍 Skill 的博客时，更建议文件名用：
codex-skill-usage.mdcodex-skill-intro.mdai-skill-guide.md不要直接叫：
skill.mdSKILL.md这样可以避免和 Codex Skill 文件规范撞名。
13. 新手写 Skill 的建议
刚开始不要追求很复杂。
先按这个顺序来：
1. 先写一个只有 SKILL.md 的 Skill2. 把 description 写清楚3. 正文只写最重要的流程规则4. 用几次后再补 references5. 重复动作稳定后再加 scripts6. 真正需要模板资源时再加 assets很多 Skill 写不好，不是因为内容少，而是因为太宽泛。
比如：
帮我处理所有编程问题这个范围太大，不适合做 Skill。
更好的方向是：
帮我写 Java 后端学习博客帮我审查 Spring Boot Controller帮我把会议纪要整理成周报帮我检查 Astro 博客文章 frontmatter范围越具体，Skill 越好用。
14. 一句话总结
Skill 的核心不是“多写一份提示词”，而是把一类重复任务沉淀成稳定流程。
新手可以先记住：
SKILL.md是 Skill 的核心文件；name写清楚技能名字；description写清楚什么时候触发；- 正文写执行流程和规则；
- 复杂资料放
references/； - 重复校验放
scripts/； - 模板资源放
assets/； - 博客文章的
category和 Skill 文件的 frontmatter 不是一回事； - 不要把普通博客文章命名成
SKILL.md或容易被误识别的skill.md。
等你能写出一个稳定的小 Skill，再慢慢拆分 references、补脚本、加模板资源，就能从“每次重新提示 AI”变成“让 AI 按固定工作流办事”。
If this article helped you, please share it with others!
Some information may be outdated