摘要 ：本文是 Agent Skills（智能体技能）的完整实操手册，从零开始讲解如何编写、测试和优化 SKILL.md 技能文件。内容涵盖：常见错误 Top 10 自查清单、核心术语速查表、30 分钟快速上手清单、推荐学习资源、50 条 description 触发词模板库，以及 20 个高频 FAQ。文末附 Codex 2026 实操更新（Part 11），重点说明 Codex 中 Skill 的目录结构（
.agents/skills/）、安装方式（$skill-installer）、创建方式（$skill-creator）以及 Goal、Plan、执行和复核四种工作模式的选择方法，帮助读者在 Codex 中高效落地 Agent Skills。
附录 A：常见错误 Top 10 自查清单写完 Skill 后，逐条对照检查：
| 序号 | 错误 | 自查问题 | 修复方法 |
|---|---|---|---|
| 1 | description 太宽泛 | 是否只有"做 XX 相关的事"？ | 补上"做什么 + 何时触发" |
| 2 | 缺触发句式 | 有没有"当用户......时触发"？ | 按万能公式补全 |
| 3 | 一个 Skill 做多件事 | 是否同时管"写目标"和"出题"？ | 拆成多个 Skill |
| 4 | name 不合法 | 有大写/空格/连续连字符？ | 改成小写+连字符 |
| 5 | 正文没有步骤 | 是不是一大段话？ | 改成步骤 1/2/3 |
| 6 | 没写输入输出格式 | AI 怎么知道输出长什么样？ | 补输入输出规范段 |
| 7 | 没有示例 | 有没有至少 1 个完整示例？ | 按 Part 5.2 补示例 |
| 8 | 没处理异常 | 用户不说全信息会怎样？ | 补边界情况段 |
| 9 | 正文超长 | 超过 500 行了吗？ | 详细资料拆到 references/ |
| 10 | 写完没测试 | 做过触发测试和 A/B 对比吗？ | 按 Part 6 跑一遍 |
附录 B：术语速查表
| 术语 | 全称 | 大白话解释 |
|---|---|---|
| Skill | Agent Skill（智能体技能） | 给 AI 装的"专业 APP"：一个装着说明书的文件夹 |
| SKILL.md | --- | 技能的主文件，AI 读它就知道该做什么 |
| YAML | YAML Ain't Markup Language | 用"冒号+缩进"写的配置文件格式 |
| Frontmatter | YAML 前置元数据 | SKILL.md 开头用 --- 包住的几行，写名字和描述 |
| description | 描述字段 | Skill 的"门面"，AI 靠它决定要不要激活这个技能 |
| Body | 正文指令 | SKILL.md 里 --- 之后的部分，写具体怎么做 |
| 渐进式披露 | Progressive Disclosure | AI 的按需加载机制：先看简介，匹配了才读全文 |
| 负触发器 | Negative Trigger | 告诉 AI"什么时候不要用我"的那句话 |
| MCP | Model Context Protocol（模型上下文协议） | 连接外部工具和数据的"插座"，和 Skill 互补 |
| Token | 词元 | AI 计量文本长度的单位，约 1 个汉字 ≈ 1-2 个 token |
| 上下文窗口 | Context Window | AI 一次能"看到"的文本总量，装太多会漏看中间内容 |
| skill-creator | 技能创作器 | Anthropic 官方技能，用来创建、评测、优化其他技能 |
| Rules | 规则 | 全局常驻的偏好指令，启动即加载，始终占上下文 |
| Conventional Commits | 约定式提交 | 一种 Git 提交信息规范，如 feat/fix/docs |
附录 C：30 分钟上手检查清单
按顺序打勾，完成即拥有第一个可用的 Skill：
- 想好一个你会重复做的任务（Part 1.1 的 5 问自测，至少 3 分）
- 用 Part 1.3 的三个问题写下 Skill 定位（核心功能/目标用户/触发场景）
- 按 Part 2.5 的路径表，在你的平台创建技能目录
- 新建 SKILL.md，写好 name 和 description（套用 Part 3.2 万能公式）
- 用 Part 4.4 的模板填 Body 四段式
- 加 1 个完整输入输出示例
- 在对话中测试触发（说触发场景里的话，看 AI 是否激活）
- 对比"有技能"和"没技能"的输出差异（Part 6.3）
- 发现问题就改，每轮只改一个问题（Part 6.5 经验）
- （可选）用 skill-creator 做专业评测，冲击 90% 触发准确率
附录 D：推荐学习资源
| 资源 | 地址/获取方式 | 适合谁 |
|---|---|---|
| Agent Skills 开放标准官网 | agentskills.io | 想了解规范细节的人 |
| Anthropic 官方技能仓库 | github.com/anthropics/skills（15 万+ Star，18 个官方技能） | 所有人，入门首选 |
| Trae 技能官方文档 | docs.trae.ai（搜索"技能"） | Trae 用户 |
| Claude Code 技能文档 | code.claude.com/docs（搜索 skills） | Claude Code 用户 |
| 《Agent Skills with Anthropic》课程 | DeepLearning.AI（吴恩达联合 Anthropic 推出） | 想系统学习的人 |
| obra/superpowers | github.com/obra/superpowers | 想学开发方法论技能的人 |
附录 E：50 条 description 触发词模板库
写 description 没灵感时，从下表挑关键词组合。按领域分组：
- 教育类：教学目标、教案、课程设计、布鲁姆、学习目标、课时计划、学情分析、教学活动、评价量规、单元设计
- 办公类：会议纪要、周报、月报、待办、日程、邮件、通知、纪要、行动项、跟进
- 写作类：标题、开头、结尾、摘要、润色、改写、扩写、缩写、提纲、文案
- 开发类：commit、PR、代码审查、注释、文档、脚手架、测试用例、重构、lint、部署
- 数据类：清洗、统计、透视、可视化、报表、对比、趋势、异常检测、预测、归因
用法：从"做什么"列选 1 个动作 + 从对应领域选 2-3 个关键词，套进万能公式。
例：动作"生成" + 教育"教学目标/布鲁姆/教案" → "根据布鲁姆分类法生成教学目标。当用户需要编写课程目标、教案目标时触发。"
附录 F：FAQ 常见问题 20 问
Q1：Skill 必须会编程才能写吗？
不用。SKILL.md 就是 Markdown 文本，会打字就能写。脚本（scripts/）是可选的进阶功能。
Q2：一个 Skill 最少需要几个文件？
1 个：SKILL.md。其他目录都是可选的。
Q3：description 写多长合适？
50-150 字。太短信息不够 AI 判断，太长浪费启动时的 token 预算。
Q4：我的 Skill 不触发怎么办？
按 Part 6.1 排查：检查 description 是否有"当用户......"句式、关键词是否够、目录路径是否对。
Q5：Skill 误触发（不该用却用了）怎么办？
加负触发器（Part 3.4），明确"不要用于......"。
Q6：SKILL.md 用什么编辑器写？
任意文本编辑器：VS Code、记事本、Typora 都行。保存为 UTF-8 编码。
Q7：能在一个 Skill 里调用另一个 Skill 吗？
能，见 Part 5.5。注意避免循环调用。
Q8：Skill 和 Cursor Rules 有什么区别？
Rules 是全局常驻偏好，始终占上下文；Skill 按需加载，更省上下文。Trae 官方建议把工作流类指令从 Rules 迁到 Skill。
Q9：Skill 能联网吗？
Skill 本身主要提供指令和资源，不自动提供联网能力；它可以指导 Codex 使用 Web Search、MCP、Connector 或其他已配置工具。
Q10：升级 Skill 后旧对话会受影响吗？
不会。已发生的对话不会重新加载，新对话才用新版 Skill。
Q11：Skill 有数量上限吗？
没有硬上限，但太多会让启动变慢（每个都要加载 name+description）。建议精简到常用的几十个。
Q12：中英文混写可以吗？
可以。name 用英文（小写连字符），description 和正文可中英文混写。
Q13：Skill 能调用本地脚本吗？
能，放在 scripts/ 目录，在 Body 里用相对路径引用。注意安全（Part 10.3）。
Q14：怎么知道 AI 加载了我的 Skill？
大多数平台会在回复里提示"已加载 XX 技能"，或你可以直接问"你加载了哪些技能"。
Q15：Skill 能分享给不用 AI 的人吗？
能，但对方需要装一个支持 SKILL.md 的 AI 工具才能用。纯文本分享只能"看"不能用。
Q16：description 里能放链接吗？
技术上能，但不建议。链接不参与语义匹配，反而占字数。
Q17：同一个功能在不同平台要写多份 Skill 吗？
不用。只要 SKILL.md 用标准字段，一份能在多平台通用。
Q18：Skill 的 License 必须加吗？
不强制，但分享时强烈建议加。没有 License 别人法律上不敢用。
Q19：Skill 能撤销/回滚吗？
Skill 是文件，用 Git 管理就能回滚到任意版本（Part 10.1）。
Q20：新手第一个 Skill 做什么好？
做你最常重复的那件事。如果没灵感，从 Part 8 的五个案例里挑一个最接近的改。
最后更新：2026 年 8 月（扩充版）。各平台界面和支持状态可能随版本变化，遇到出入时以对应平台的官方文档为准。
重要修订提示：Codex 当前用法以 Part 11 为准
本手册原有内容主要讲 Agent Skills 的通用写法，仍可作为入门基础。由于 Codex 的目录、安装入口和桌面能力已经更新，涉及 Codex 的旧表格、旧命令和旧路径请以 Part 11 的说明覆盖。
本次更新的核心结论：项目级 Skill 使用 .agents/skills/；用户级 Skill 使用 ~/.agents/skills/；安装精选 Skill 使用 $skill-installer；创建 Skill 使用 $skill-creator；分发多个 Skill 或连接器时使用 Plugins。
Part 11：Codex 2026 实操更新（个人学习版）
11.1 Skill 在 Codex 中是什么
Skill 是可复用的工作流说明包：一个包含 SKILL.md 的目录，可选 scripts/、references/、assets/，还可以添加 agents/openai.yaml 作为 Codex 的界面元数据、调用策略和工具依赖配置。Skill 不是插件市场本身，也不是 MCP Server。
Codex 会先读取每个 Skill 的 name、description 和路径，只有判断任务匹配时才读取完整 SKILL.md。这是渐进式披露机制。Skill 太多时，初始列表可能被压缩或省略部分 Skill，因此 description 要把核心用途和触发关键词放在前面。
11.2 Codex 识别 Skill 的目录
- 项目级 （推荐团队和项目共享）：当前工作目录或其父级目录中的
.agents/skills/，一直扫描到仓库根目录。 - 用户级 （个人所有项目使用）：
~/.agents/skills/。 - 管理员级 ：
/etc/codex/skills/。系统级 Skill 由 Codex 或平台提供。Codex 也支持符号链接目录。
如果两个 Skill 的 name 相同，Codex 不会自动合并它们；它们可能同时出现在选择器中。
11.3 查看、显式调用和自动触发
在 Codex CLI 或 IDE 扩展中，可以使用 /skills 查看 Skill，或使用 $skill-name 显式调用。例如：$skill-creator 创建一个会议纪要 Skill。
不显式调用时，Codex 会根据 description 进行隐式匹配。隐式匹配适合日常使用；对重要流程、容易误触发或需要稳定复现的任务，建议显式使用 $skill-name。
如果要禁止某个 Skill 自动触发，可以在 agents/openai.yaml 中设置 policy.allow_implicit_invocation: false；这样仍可通过显式调用使用。
11.4 当前安装方式
安装精选 Skill ：在 Codex 中输入 $skill-installer linear，或输入其他精选 Skill 名称。也可以提示安装器从指定仓库下载 Skill。安装后 Codex 通常会自动发现；如果没有出现，重启 Codex。
安装插件 ：桌面版使用 Plugins 页面浏览和安装；Codex CLI 使用 /plugins 打开插件浏览器。插件可以同时携带一个或多个 Skill、Connector、MCP Server、资源和 Hooks。IDE 扩展不提供插件浏览器。
安全边界：安装器不是"自动扫描全网并安全判断"的工具。第三方 Skill、插件脚本、MCP Server 和 Hooks 都应先检查来源、代码、权限和数据访问范围。
11.5 创建和维护 Skill
- 创建方式一 ：显式调用
$skill-creator，让 Codex 询问功能、触发条件、输入输出和脚本需求。 - 创建方式二：手动创建目录和 SKILL.md。
- 创建方式三：如果已有一套重复的操作流程，可以使用 Record & Replay 生成 Skill 草稿。
Codex 会自动检测 Skill 的变化；如果更新没有显示，重启 Codex。可以在 ~/.codex/config.toml 中通过 [[skills.config]] 和 enabled = false 暂时禁用某个 Skill，而不必删除文件。
建议的 Skill 验收：至少准备正向触发、负向触发、缺少输入、多个 Skill 竞争、显式调用和脚本失败六类测试；不要把"90% 触发准确率"当作官方硬性标准。
11.6 Skill、Plugins、MCP、Connector 和 Tool Search 的区别
- Skill：封装工作流、知识和输出规范。
- Plugins：分发一个或多个 Skill，并可携带连接器和 MCP。
- MCP Server：提供外部工具或数据访问。
- Connector：面向具体外部服务的连接能力。
- Tool Search：帮助模型寻找可用工具，不是 Skill 安装器。
11.7 Goal、Plan、执行和复核怎么选
Goal（目标） 是长期、多步骤任务模式。可以输入 /goal，目标文本会同时成为初始任务和完成标准，并在界面上显示进度，可暂停、继续、编辑或清除。目标应写清结果、限制和验收条件。
Plan（计划模式） 适合先分析文件、澄清范围、制定修改清单和测试标准。计划阶段不等于已经修改文件。若需求明确且风险低，可以直接执行；若涉及多个文件、格式转换或不可逆操作，先 Plan 更稳妥。
执行阶段：关闭计划模式后，要求 Codex 按已确认方案修改文件，并选择合适的运行环境和权限。
复核阶段：再次提出只读审阅要求，检查输出是否满足验收标准。
本手册中的 Ask、Code、Plan 是工作方式的简化叫法，不要把它们误解为 Skill、Plugin 或 MCP 的安装入口。当前官方入口重点是 /goal、/plan、/skills、$skill-installer、$skill-creator 和 /plugins。
11.8 本手册后续维护规则
涉及路径、命令、插件名称、平台支持和界面按钮的内容，都要附官方链接和核验日期。数量、Star、平台列表和"最新"措辞必须注明时间，不能写成永久事实。
本章核验日期：2026-08-14。官方资料入口：developers.openai.com/codex/skills、developers.openai.com/codex/plugins、learn.chatgpt.com/docs/long-running-work。