AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗仓库 ↗

CX-06 Skills 完整指南：在 App 中调用和编写可复用工作流 ​

主要来源：OpenAI Codex Skills 官方文档、Codex App Features、Plugins 文档。

课程信息

📚 本课学习目标 ​

完成本课学习后，你将能够：

  1. 理解Skill的本质：掌握Skill是可复用工作流，不是快捷命令
  2. 判断什么时候升级成Skill：一个流程重复三次以上、团队多人需要时就该沉淀
  3. 编写规范的Skill：写出目标明确、触发清晰、步骤可执行、输出稳定的SKILL.md
  4. 管理Skill资源：合理组织references/和scripts/，不藏危险脚本
  5. 区分Skills与其他能力：清楚Command、Skill、Automation、MCP、Plugin各自的分工
  6. 团队共享Skill：通过项目级.agents/skills/或 Plugin 打包分发
  7. 自查Skill质量：从触发、输出、权限、平台、资源、维护六个角度核对
  8. 避免Skill反模式：不写不可验证的口号、不写密钥、不伪装工具API

🗺️ 学习路径导航（先看这里！） ​

💡 根据你的情况选择学习路径：不用全看！

路径A：快速上手（⏱️ 15分钟） ​

适合人群：想快速写一个团队复用的Skill

只看这些章节：

✅ 第1部分：Skill是什么（2分钟）
✅ 第3部分：Skill的文件结构（5分钟）
✅ 第4部分：好Skill的标准（3分钟）
✅ 第5部分：什么时候从prompt升级成Skill（5分钟）

路径B：完整学习（⏱️ 2-3小时） ​

适合人群：想系统掌握Skill开发、共享和治理

学习顺序：从头到尾所有章节

术语表（小白必读） ​

Skill 的学习重点不是"会创建一个文件夹"，而是知道什么时候该把一次提示沉淀成可复用能力。

术语一句话解释新手注意
Skill可复用的任务说明、资源和可选脚本本质是工作流，不是普通快捷键
SKILL.mdSkill 的入口说明文件必须写清触发条件、流程和输出
FrontmatterSKILL.md 顶部的 name / description 等元数据description 决定隐式触发质量
Progressive disclosureCodex 先看到 Skill 摘要，需要时再读全文Skill 列表太大时描述可能被缩短
Explicit invocation用户点名 $skill-name最稳定，适合教学和团队流程
Implicit invocationCodex 根据 description 判断要不要用依赖描述是否准确
references/Skill 附带的参考资料放大段规范，不要塞满入口文件
scripts/Skill 附带的可选脚本有真实副作用，要写清权限
agents/openai.yamlApp UI metadata 和策略配置可设置展示、依赖、隐式调用策略
PluginSkill 的分发包装方式之一想分享给更多人时再打包

一句话：Skill 把“每次都要重复说的话”变成“稳定、可触发、可维护的流程”。

0. Skill 的工作机制 ​

老金我把 Skills 当作可复用判断，不是简单 prompt 收藏；能复用的必须包含步骤、边界和验收方式。

Codex 使用 Skill 的过程大致是：

text
启动时扫描可用 Skills
  -> 把 name / description / path 放进初始上下文
  -> 用户点名或任务匹配 description
  -> Codex 读取对应 SKILL.md
  -> 必要时再读取 references、调用 scripts 或工具
  -> 按 Skill 约定输出结果

这就是为什么 Skill 的 description 很重要。它不是介绍文案，而是触发路由。写得太泛，Codex 可能乱用；写得太窄，真正需要时触发不了。

0.1 一个流程什么时候值得做成 Skill ​

信号说明是否适合 Skill
同一提示复制三次以上说明流程稳定重复适合
多人需要同一做法需要团队一致性适合
输出格式总要固定方便 Review、PR、报告适合
需要附带规范或模板references 能降低入口长度适合
只做一次的临时任务没有复用价值不适合
需要实时调外部 API工具连接更重要先看 MCP / Connector
需要每天运行调度更重要Automation 调用 Skill

0.2 Skill 设计的三个边界 ​

  1. 触发边界：什么时候应该用，什么时候不该用。
  2. 执行边界：能读什么、能写什么、是否能跑脚本。
  3. 输出边界：最后交付什么格式，先报告问题还是先总结。

很多 Skill 不好用，是因为只写了“你是一个专家”，却没写边界。好的 Skill 应该让 Codex 知道“在什么场景下，按什么步骤，产出什么结果，哪些事不要做”。

1. Skill 是什么 ​

Skill 是一组可复用指令、资源和可选脚本。它不是单纯"快捷命令"，而是一套工作流。

适合：

  • 代码审查流程。
  • 文档核对流程。
  • 发布检查。
  • 写作规范。
  • 团队固定 SOP。

不适合：

  • 只执行一次的临时任务。
  • 需要实时外部 API 的工具连接。
  • 需要定时运行的周期任务。

2. App 中怎么调用 Skill ​

常见方式：

text
$code-review 审查当前 diff，重点看安全、测试和边界情况。

或自然语言触发：

text
按我们的代码审查 Skill 检查这次改动。

App 也可能通过插件提供 Skills。可用 Skills 取决于当前 App、插件、项目和用户目录。

调用前先确认三件事：

  1. 当前 App 是否能看到这个 Skill。
  2. 这个 Skill 是用户级、项目级，还是插件带来的。
  3. 它会不会读取额外资源、运行脚本或调用工具。

如果点名 $skill-name 没有触发，先检查名称、路径、插件是否安装，以及 App 当前会话是否已加载。

3. Skill 的文件结构 ​

最小结构：

text
.agents/skills/code-review/
  SKILL.md

放在哪里要分清：

位置适合
项目级 .agents/skills/当前仓库专用 SOP
用户级 skills 目录个人跨项目复用
插件内 Skill团队或市场分发的能力包

项目级 Skill 更适合教程，因为读者打开仓库就能看到规则；用户级 Skill 适合个人工作流，不应该写进团队仓库。

示例：

markdown
---
name: code-review
description: Review code changes for bugs, regressions, security risks, and missing tests.
---

# Code Review

## Workflow
1. Inspect the current diff.
2. Identify behavior changes.
3. Look for bugs, security risks, and missing tests.
4. Report findings first, ordered by severity.

## Output
- Findings with file and line references.
- Open questions.
- Test gaps.

## Rules
- Do not rewrite code unless explicitly asked.
- Do not praise changes before listing findings.

4. 好 Skill 的标准 ​

标准说明
目标明确一句话说清它解决什么问题
触发清晰用户点名或描述能稳定触发
步骤可执行不写空泛原则
输出稳定有明确交付格式
资源最小只带必要参考文件和脚本
安全边界明确写清哪些动作不能做

4.1 description 怎么写 ​

description 是 Skill 的触发说明。推荐格式：

text
Use when [任务场景]. Do [核心动作]. Do not use when [边界].

例子：

yaml
description: Use when reviewing code changes for correctness, regressions, security risks, and missing tests. Report findings first. Do not use for general code generation.

不要写：

yaml
description: Helps write high quality code.

因为它既不说明触发场景，也不说明边界。

4.2 SKILL.md 推荐结构 ​

markdown
---
name: code-review
description: Use when reviewing changed code for bugs, regressions, security risks, and missing tests. Report findings first.
---

# Code Review

## When To Use
- Current diff or PR needs review.
- User asks for review, audit, or risk check.

## Do Not Use
- User asks to implement a feature from scratch.
- There is no code diff or target file.

## Workflow
1. Inspect the diff.
2. Identify behavior changes.
3. Check correctness, security, tests, and scope.
4. Report findings first, ordered by severity.

## Output
- Findings with file / line references.
- Open questions.
- Verification gaps.

这个结构比“角色定义 + 你很专业”更可执行。

5. 什么时候从 prompt 升级成 Skill ​

满足任一条件就考虑 Skill：

  • 同一流程重复使用三次以上。
  • 团队多人需要统一做法。
  • 流程包含多个检查步骤。
  • 需要附带模板、脚本或参考文档。
  • 希望被 Automation 调用。

临时任务不要急着写 Skill。

6. Skills、Commands、Automations 的分工 ​

需求首选
当前线程快速动作Command
固定 SOP / 复用流程Skill
定时或后台重复执行Automation
外部工具连接MCP / Connector
打包分发一组能力Plugin

例子：

  • /review 是 Command。
  • $code-review 是 Skill。
  • “每天早上 review 未合并 PR”是 Automation + Skill。

7. 带资源的 Skill ​

复杂 Skill 可以带资源：

text
my-skill/
  SKILL.md
  references/
    checklist.md
    style-guide.md
  scripts/
    validate.js

原则：

  • 大段参考资料放 references/。
  • 重复性强、容易写错的逻辑放 scripts/。
  • SKILL.md 只写入口、流程、路由规则和必要摘要。

带脚本的 Skill 要额外写清：

  • 脚本需要什么运行时。
  • 是否会写文件。
  • 是否会联网。
  • 失败时输出什么。
  • 是否能在 Windows / macOS 都跑。

不要把一段危险脚本藏在 Skill 里让 App 自动执行。

7.1 Progressive disclosure 怎么影响文件组织 ​

Codex 初始只看 Skill 的摘要，不会一开始把所有参考资料都塞进上下文。你应该这样组织：

内容放哪里原因
触发场景、流程、输出SKILL.mdCodex 必须先看到
长规范、示例、术语表references/需要时再读，省上下文
可重复机械检查scripts/比模型手写更稳定
图片、图标、UI metadataassets/、agents/openai.yamlApp 展示和依赖说明

不要把 20 页规范全部复制到 SKILL.md。入口文件越长，越难维护，Codex 也更难快速抓住触发和流程。

7.2 带脚本 Skill 的安全写法 ​

带脚本时必须写清：

markdown
## Scripts

- `scripts/check-links.js`
  - Purpose: check internal markdown links.
  - Reads: docs/**/*.md
  - Writes: nothing by default.
  - Network: no.
  - Runtime: Node.js 20+.
  - Failure: print broken links and exit non-zero.

如果脚本会写文件、联网、调用外部服务，必须在 Skill 里明确说明，并让当前权限和审批策略接住它。

8. 团队共享 ​

团队共享方式：

方式适合
项目级 .agents/skills/当前仓库专用
用户级 skills 目录个人跨项目复用
Plugin打包给团队或市场分发

团队 Skill 要避免写个人路径、个人 token、个人偏好。

共享前自查：

项标准
触发点名和自然语言都能稳定触发
输出结果格式稳定，方便 Review
权限不默认要求危险权限
平台Windows / macOS 路径写法不冲突
资源references 和 scripts 都能按相对路径找到
维护有 owner，知道谁负责更新

9. Skill 与插件 ​

Plugin 可以携带 Skills，但 Skill 不等于 Plugin。

能力关系
Skill一个可复用工作流
Plugin一个能力包，可以包含多个 Skills、MCP、Apps、配置

当你只需要一个团队审查流程，用 Skill。需要打包 GitHub 连接器、MCP、多个 Skills、配置时，才考虑 Plugin。

10. 常见反模式 ​

反模式问题
“做高质量代码”不可验证
在 Skill 里写密钥安全风险
把工具 API 伪装成 Skill应该用 MCP
把长期周期任务写成 Skill应该用 Automation 调用 Skill
一个 Skill 解决所有事边界过大，难维护

10.1 Skill 排障表 ​

症状可能原因处理
点名 $skill 没触发名称写错、Skill 未加载、路径不在扫描范围查 App Skills 列表或重启 Codex
自然语言没触发description 太泛或太隐晦重写 description，加入触发词
触发了错误 Skill多个 Skill 名称 / 描述重叠缩小描述，明确 Do Not Use
Skill 输出不稳定没写输出格式在 Output 中固定结构
Skill 读错资料references 路径不清在流程里说明何时读取哪个文件
脚本运行失败runtime、路径、权限或平台问题写清运行时，测试 Windows / macOS
团队成员看不到Skill 放在个人目录放项目 .agents/skills/ 或打包 Plugin

10.2 Skill 版本和维护 ​

团队 Skill 一旦多人使用，就要有维护纪律：

项建议
Owner每个 Skill 有负责人
Changelog大改触发条件或输出格式时记录
测试提示保留 3-5 条典型触发 prompt
回滚出问题能回到旧版
安全审查带脚本或工具依赖的 Skill 要 Review

Skill 是团队知识资产，不是一次性 prompt 草稿。

11. 课堂工坊：把重复提示沉淀成 Skill ​

案例一：从一段 prompt 升级为 SKILL.md ​

目标：把“每次都要说的代码审查要求”变成项目级 Skill。

  1. 创建目录：
text
.agents/skills/code-review/
  SKILL.md
  1. 写入最小 Skill：
markdown
---
name: code-review
description: Review changed code for correctness, security, and missing tests.
---

# Code Review

## Workflow
1. Read the current diff.
2. Check correctness, security, test coverage, and scope creep.
3. Report findings first, ordered by severity.
4. Do not modify files unless the user asks for fixes.

## Output
- Findings
- Open questions
- Verification notes
  1. 在 App 新线程中触发：
text
使用 $code-review 审查当前 diff。只报告问题，不修改文件。

你应该看到：输出按 findings 优先，而不是泛泛总结；没有新增 diff。

案例二：给 Skill 加 references ​

目标：让 Skill 引用团队固定规范，而不是把所有内容塞进入口文件。

text
.agents/skills/release-check/
  SKILL.md
  references/
    release-policy.md

在 SKILL.md 里写清什么时候读取 references/release-policy.md。你应该看到：Codex 只在发布检查任务中加载这份参考，不会把 release 规则误用于普通修 bug。

案例三：Plugin 中的 Skill 和项目 Skill 怎么选 ​

目标：理解分发边界。

场景放哪里
当前仓库专用 SOP.agents/skills/
个人跨项目习惯用户级 skills 目录
团队要安装、启用、卸载的一组能力Plugin

练习提示：

text
这个流程只服务当前仓库。请帮我判断它应该做成项目级 Skill、用户级 Skill，还是 Plugin，并说明理由。不要创建文件。

你应该看到：Codex 根据复用范围、权限和分发方式做判断，而不是默认都做成插件。

12. Skill Cookbook：四类高价值 Skill ​

12.1 Code Review Skill ​

适合每个工程团队的第一个 Skill。

markdown
---
name: code-review
description: Use when reviewing code changes for correctness, regressions, security risks, missing tests, and scope creep. Report findings first. Do not use for implementation.
---

# Code Review

## Workflow
1. Inspect the current diff or PR diff.
2. Identify behavior changes.
3. Check correctness, security, performance, tests, and scope.
4. Report findings first, ordered by severity.

## Output
- Findings with file and line references
- Open questions
- Verification gaps
- Suggested next action

## Rules
- Do not modify files unless explicitly asked.
- Do not praise before findings.
- Do not invent test results.

12.2 Release Readiness Skill ​

适合发布前检查。

markdown
---
name: release-readiness
description: Use before a release to check changelog, tests, docs, migration notes, and rollback risk. Do not deploy.
---

# Release Readiness

## Workflow
1. Read release notes or changelog.
2. Check changed files and migration notes.
3. Verify relevant test / build commands.
4. Identify missing docs, rollback gaps, and risky dependencies.

## Output
- Ready / Not ready
- Blocking issues
- Non-blocking follow-ups
- Verification evidence
- Rollback notes

12.3 Docs Drift Skill ​

适合课程、README、开发文档维护。

markdown
---
name: docs-drift-check
description: Use when checking whether docs match current repository commands, config, and source behavior. Report drift with evidence. Do not rewrite docs unless asked.
---

# Docs Drift Check

## Workflow
1. Read target docs.
2. Read source-of-truth files such as package.json, AGENTS.md, config, scripts, or official docs.
3. Compare claims with evidence.
4. Report drift and suggested edits.

## Output
- Document location
- Claim
- Source of truth
- Drift type
- Suggested correction

12.4 Security Triage Skill ​

适合把“安全检查”变成稳定流程。

markdown
---
name: security-triage
description: Use when triaging a suspected security issue in code, config, MCP, plugins, automations, or cloud setup. Report impact and containment steps first.
---

# Security Triage

## Workflow
1. Identify asset, entry point, and affected scope.
2. Check whether secrets, production data, permissions, or external services are involved.
3. Separate confirmed facts from assumptions.
4. Recommend containment, verification, and follow-up.

## Output
- Severity
- Affected files / systems
- Evidence
- Immediate containment
- Follow-up fixes

12.5 Skill 评审问题 ​

每个 Skill 合并前问：

问题为什么
description 是否能准确触发？决定是否会误用
Do Not Use 是否写清？防止泛化
输出格式是否稳定？方便 Review 和自动化
是否需要 references？避免入口文件过长
是否需要 scripts？有脚本就有安全和平台问题
是否适合项目级而非用户级？团队复用要放仓库
是否能被 Automation 调用？需要耐久 prompt

常见问题 ​

Q1：Skills 是 slash commands 吗？ ​

不完全是。Skill 可以被点名触发，也可能显示成命令入口，但本质是可复用工作流。

Q2：Codex App 会自动加载所有 Skills 吗？ ​

取决于当前会话、项目、用户目录和插件。以 App 当前可见列表为准。

Q3：Skill 能运行脚本吗？ ​

可以引用脚本资源，但是否执行取决于权限和当前环境。脚本要最小权限、可审计。

Q4：为什么我的 Skill 没有被自动使用？ ​

最常见原因是 description 不够清楚。先用 $skill-name 显式触发验证流程，再优化 description 做隐式触发。

Q5：项目级 Skill 和用户级 Skill 冲突怎么办？ ​

不要依赖自动合并。两者可能同时出现。团队流程优先放项目级，个人习惯放用户级，名称尽量避免重复。

Q6：Skill 要不要写很多人设包装？ ​

不需要。语气设定可以帮助表达，但真正决定质量的是触发边界、流程、输入、输出、禁止事项和验证方式。

Q7：什么时候把 Skill 打包成 Plugin？ ​

当它要跨项目、跨团队分发，或者需要和 MCP、Connector、配置、UI metadata 一起安装时，再打包成 Plugin。单仓库 SOP 放 .agents/skills/ 就够。

13. Skill 设计的核心：让流程可重复，而不是让 prompt 更长 ​

Skill 的价值不是把一大段 prompt 换个地方存起来。它的价值是把一个高频、可复用、边界清楚的工作流变成 Codex 能稳定发现和执行的能力。

13.1 好 Skill 的四个特征 ​

特征说明
触发清楚description 里写明什么时候用
边界清楚也写明什么时候不用
输入输出清楚Codex 知道读什么、交付什么
内容分层常用指令在 SKILL.md，长资料放 references

13.2 Skill 不该承载什么 ​

text
- 一次性任务。
- 当前项目的临时 bug。
- 模糊人设包装。
- 需要每天变化的命令。
- 真实密钥或私有账号信息。

一次性任务放 prompt。项目事实放 AGENTS.md。可复用流程才放 Skill。

14. description 写作课 ​

Codex 初始只看到 skill 的 name、description 和路径。description 写不好，Skill 就很难被自动选中。

14.1 差 description ​

yaml
description: A powerful helper for many tasks.

问题：没有触发词，没有边界，没有具体任务。

14.2 好 description ​

yaml
description: Review Markdown course chapters for factual consistency, broken commands, missing learner steps, and Chinese readability. Use when editing docs or course material; do not use for source code review.

好在哪里：

  • 有对象：Markdown course chapters。
  • 有动作：review factual consistency、commands、steps、readability。
  • 有触发场景：editing docs or course material。
  • 有边界：do not use for source code review。

14.3 description 模板 ​

text