📚 Skills + Shell 进阶

三个核心概念

Skills（技能）：可重复调用的操作手册

Skills 是把一类重复工作封装成一个 Codex 可以调用的"操作手册"。Codex 看 Skill 的描述就知道什么时候用它、怎么用。

适合做什么：

• 日志归因分析
• 起草发布说明
• 按 checklist 做 PR 审查
• 制定迁移计划
• 标准化的 Debug 流程
• Incident 总结报告

规则：同样的提示词反复用超过 2-3 次，就该变成 Skill。

Shell 工具：给 Codex 一个真实的终端

Codex 默认能用 Shell 跑命令，但很多场景需要更长寿的容器、网络访问、文件持久化。Shell 工具让 Codex 在沙箱里跑命令、读写文件、装依赖、调 API。

典型用法：

• 安装项目依赖（pip install、npm install）
• 拉取数据（curl、wget）
• 跑测试、Lint、Build
• 调用 git、docker、kubectl

上下文压缩：防止长任务被撑死

长会话上下文会膨胀，触达模型上下文上限会被截断。Codex 内置 auto compact：达到阈值后自动总结历史保留要点。

# config.toml
model_auto_compact_token_limit = 900000   # 1M 模型推荐留 100K 缓冲

为什么要一起用？

• 单独 Skill：能复用但跑不完整工作流
• 单独 Shell：能跑命令但每次都重新提示
• 单独压缩：能跑久但没有结构化能力
• 三者组合：能跑长任务（compaction 兜底）、能复用流程（Skills）、能执行实操（Shell）

10 条实用技巧

1. Skill 的描述要回答三个问题

每个 Skill 在创建时都有一个 description，Codex 靠这个判断什么时候触发该 Skill。描述必须回答三个问题：

1. 这个 Skill 做什么？
2. 什么场景应该用它？
3. 什么场景不应该用它？

❌ 模糊描述：

description: 帮助处理日志

✅ 具体描述：

description: |
  用于分析生产环境 nginx 错误日志（access.log/error.log），输出错误归因报告。
  应该用：定位 5xx、502、超时、跨域等错误的根因。
  不应该用：业务侧的应用日志分析；那些用 app-log-analyzer skill。

2. 加上反面例子，减少误触发

在 Skill 描述里显式列出不该用的场景，能大幅减少模型误判：

description: |
  ...
  反面例子：
  - 用户问"如何配置 nginx"——这是配置帮助，不是日志分析
  - 用户问"我的 API 报 500"——直接查源码，不需要日志归因

3. 模板和示例放进 Skill，不要堆在系统提示词里

Skill 是有声明文件（SKILL.md）和资源目录的。长模板、复杂示例、checklist 放在 Skill 资源里，让主提示词保持精简。

skills/
└── release-notes/
    ├── SKILL.md           # 描述 + 触发规则
    ├── template.md         # 发布说明模板
    └── examples/
        ├── good.md
        └── bad.md

4. 一开始就规划好容器复用和压缩

跑长任务前，先想清楚：

• 容器在多任务之间复用吗？复用就别每次 pip install
• 多少 token 触发 compact？默认 80% 上限即可
• 压缩后保留什么？关键决策、未完成任务、错误信息

提前在 AGENTS.md 里写明 compact 时该总结什么、丢什么。

5. 需要确定性时，直接告诉模型用哪个 Skill

模型有时候不会主动调 Skill。可以直接喊它名字：

> 用 `release-notes` skill 给本次发布起草说明。
> 用 `pr-review` skill 审查 #1234 PR。

或者在 AGENTS.md 里规定："涉及 PR 审查必须调用 pr-review skill。"

6. Skill + 网络访问 = 高风险，要谨慎设计

Skill 一旦能联网（curl、wget、npm 等），就有数据泄露风险。建议：

• 在 Skill 描述里明确网络白名单：「仅允许访问 *.internal.corp 和 github.com」
• 在 sandbox 层设网络限制（见 auto_review）
• 敏感 Skill（如能读 .env）单独审计，不允许进入自动审批

7. 用 Shell tool 把外部状态拉进来，而不是让模型猜

✅ 让 Codex 跑命令拿真实数据：

> 运行 `git log --oneline -20` 看最近改动
> 跑 `npm outdated --json` 看哪些依赖过期

❌ 让模型凭空猜：

> 帮我猜一下我最近改了哪些东西

8. 网络白名单是两层结构

Codex 的网络访问有两层：

1. 沙箱层：config.toml 的 sandbox_mode 限制（workspace-write 默认不许联网）
2. Skill 层：单个 Skill 可以声明只允许访问哪些域

两层都需要放行，Skill 才能联网。漏掉任意一层，请求都会被拦截。

9. 用 /compact 主动压缩长会话

长会话不要等触发自动压缩。主动 /compact 控制时机：

> /compact 保留：本次重构的目标、已改完的文件清单、剩余 TODO

显式告诉模型保留什么，比让它自己总结更靠谱。

10. 本地开发 + 云端部署，Skills 保持不变

Skills 是声明式的，与运行环境解耦。本地装的 Skill 在云端 / 团队共享的 Codex 实例上也能跑，前提是：

• Skill 不依赖本地特定路径（不要写 /Users/me/...）
• 不依赖未声明的工具（要 git、jq 都在 Skill 元数据里声明）
• 用相对路径和环境变量

三种组合模式

模式 A：安装依赖 → 拉取数据 → 生成文件

适合一次性数据处理任务。

> [Shell] pip install pandas requests
> [Shell] curl https://api.example.com/data > raw.json
> [Skill: data-analyzer] 分析 raw.json，输出图表

模式 B：Skills + Shell 实现可重复工作流

适合每周/每月跑一次的固定任务。

> [Skill: weekly-report]
    ↓
  [Shell] git log --since='1 week ago' --pretty=format:'%h %s'
    ↓
  [Skill] 提取关键改动 + 写周报
    ↓
  [Shell] echo "$REPORT" | mail -s "Weekly" team@corp.com

封装成 Skill 后，每周只需要一句"跑 weekly-report skill"。

模式 C（进阶）：Skills 作为企业工作流载体

把企业级流程（发布、安全审查、合规审计）做成 Skills，团队共享：

~/.codex/skills/
├── release-pipeline/        # 发布流程
├── security-review/         # 安全审查
├── incident-response/       # 故障响应
└── compliance-audit/        # 合规审计

新人 onboarding 只需要装一份 Skills 包，整个流程就跑通了。

快速总结

下一步