← 返回 Blog
UseAIAPIAI API2min

Codex Skills 完全实战：自己写一个"项目专属代码审查 Skill"并绑进全局工作流

当隔壁团队已经让 Codex 自己做 Code Review 时，你还在手动给每个 PR 写评审意见。 不是 AI 帮你写代码，是 AI 在审别人写的代码。前者的收益是省打字时间，后者的收益是省整个团队在代码审查上的认知负荷。而这件事的核心，叫 Skills（技能模块）—— 一套把 "你们团队怎么干活" 封装成可复用模块的规范。

ChatGPTCodex

技术前沿：当 AI 接管代码审查，Skill 正在重构团队开发工作流

当隔壁团队已经让 Codex 自己做 Code Review 时，你还在手动给每个 PR 写评审意见。

不是 AI 帮你写代码，是 AI 在审别人写的代码。前者的收益是省打字时间，后者的收益是省整个团队在代码审查上的认知负荷。而这件事的核心，叫 Skills（技能模块）—— 一套把 "你们团队怎么干活" 封装成可复用模块的规范。

一、Skill 是什么：把 "团队工作流手册" 变成可执行模块

Skill 的本质是 Codex CLI、Codex App 里的标准化技能包，基于开放 Agent Skills 标准：把团队长期积累的流程、开发规范、工具调用逻辑打成包裹，让 Agent 能可靠复现。说白点：

Skill = 你们团队的工作流手册，但不是给人读的 PDF，是给 AI 执行的标准作业程序（SOP）。

一个 Skill 就是一个目录，核心骨架必须包含 SKILL.md（YAML 前置元数据 + Markdown 指令）：

plaintext

my-skill/
├── SKILL.md              # 必需：名称 + 描述 + 指令正文
├── scripts/              # 可选：可执行脚本（确定性操作放这）
├── references/           # 可选：参考文档、规范、查表
├── assets/               # 可选：模板、图标、报告格式文件
└── agents/
    └── openai.yaml       # 可选：显示名、图标、调用策略、MCP依赖

SKILL.md 的前置元数据是路由元数据 ——Codex 靠 name 和 description 判断 "该不该激活这个 Skill"，而不靠文件名猜测：

yaml

---
name: codex-review
description: >
  审查本地代码变更或PR改动。聚焦安全漏洞、边界条件、
  架构一致性和团队代码规范。当需要进行code review时触发。
version: 1.0.0
tags: [review, security, quality, pull-request]
---

Codex 的核心加载机制叫渐进式披露（Progressive Disclosure）：

  • 启动时只加载元数据（name/description/path/openai.yaml）→ 不爆上下文
  • 匹配到任务后才读完整 SKILL.md 正文 → 再按需调用 scripts/references

这意味着：description 写得模糊 = Skill 永远不会被正确触发。description 不是注释，是路由规则 ——OpenAI 官方原话：它决定 Codex 启动时 "要不要把这个 Skill 放进候选列表"。

经验法则：description 要写清触发场景和反例（when it should NOT trigger），触发关键词前置，就算被截断也能匹配。

而且 Skills 基于开放标准，Codex 和 Claude Code 共享同一套.agents/skills/发现逻辑 —— 一份 Skill，两个 Agent 体系都能读（Claude Code 侧通过 CLAUDE.md 的 @引用或直接识别目录）。

二、手把手写一个 codex-review Skill（PR 审查包）

Step 1：创建目录

在项目根执行（仓库级，提交到 git）：

bash

运行

mkdir -p .agents/skills/codex-review
cd .agents/skills/codex-review

Codex 的扫描规则：从当前工作目录一路向上扫到仓库根，找每个目录下的.agents/skills/，所以放在$REPO_ROOT/.agents/skills/就是对全仓库生效的团队级 Skill。

Step 2：编写核心 SKILL.md

yaml

---
name: codex-review
description: >
  审查本地代码变更或PR diff。
  触发场景：用户说"review this PR / 帮我看看这次改动 / 审一下 diff"。
  不用于：纯格式美化、自动apply fix（那是另一个Skill的活）。
version: 1.0.0
tags: [review, security, quality, pull-request]
---

## 定位
团队的**统一代码审查执行器**。所有PR在进入主干前必须通过此Skill的处理。

## 执行步骤
1. **确定审查范围**
   - 如果给了PR号：跑 `gh pr diff <NUM>` 拿diff
   - 否则默认：`codex review --uncommitted`（或 `--base main`）

2. **读仓库宪法**
   从仓库根读 `AGENTS.md`，拿到：
   - 代码规范（命名风格、注释约定、目录边界）
   - NEVER条款（禁手写SQL、禁生产环境破坏命令、禁碰`infra/`等）
   - 架构边界（哪些目录能改、哪些只能走migration）

3. **按优先级逐项检查**
   - 🔴 **安全漏洞**：SQL注入模式、XSS向量、硬编码凭据、`path.join`未校验、未鉴权的内部路由
   - 🟡 **代码规范**：命名风格、import分组、与AGENTS.md声明不一致
   - 🟡 **边界条件**：null/undefined传播、异常处理被吞（`try {} catch(e) {}`空的）、输入校验缺失
   - 🔵 **架构一致性**：新代码是否塞进了正确模块/正确层

4. **输出审查报告**
   每条发现一行：
   
   [HIGH] src/auth/login.ts:47 - 鉴权中间件可绕过（early return前未校验token吊销）→ 建议：在verifyToken后加吊销检查

   - 末尾汇总：`BLOCKING=x  WARNING=y  INFO=z`
   - **最终裁决**：`APPROVE` / `REQUEST-CHANGES`（只要有BLOCKING → REQUEST-CHANGES）

## 禁令
- 审查报告不得写"LGTM / 看起来没问题"就结束——发现必须逐条列出
- diff未读完前不得下结论
- 不得跳过AGENTS.md的NEVER条款
---

一个关键经验：要求 Agent 用 MUST/must not，而不是 prefer/should—— 后者给它留了太多绕路空间。Skill 的指令要像规范，不像建议。

Step 3：把 AGENTS.md 的 NEVER 条款绑定进来

AGENTS.md 是整条 AI 工作流的 "宪法"。Review Skill 第一步就读它，本质上就是让审查自动对齐团队红线。

进阶玩法：Skill 跑完后做一轮合规校验 —— 如果生成的代码违反了 AGENTS.md 的 NEVER 条款，直接标 BLOCKING，并在 PR comment 里写明 "违反哪条 NEVER"，AI 的修复 PR 也必须过人工 review。

Step 4：放置与验证

表格

层级路径用途
仓库级（推荐提交）$REPO_ROOT/.agents/skills/全仓库共享，随 git 走
用户全局~/.agents/skills/你跨项目都要用的个人 Skill
系统级/etc/codex/skills/容器内强制下发

Codex 会自动扫描这些位置。放好后运行：

bash

运行

# 审查未提交的改动
codex review --uncommitted

# 或对着main做diff审查
codex review --base main

Skill 会自动被发现并激活；如果改了 SKILL.md 没生效，重启 Codex。

三、把 Skill 钉进团队全局工作流（这才是真正的价值）

自己做 Skill 不够，让它变成交付管道的零件才行。

① GitHub Actions：PR 一开就自动跑审查

.github/workflows/codex-review.yml：

yaml

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # 需要完整历史才能--base main正确diff

      - name: Install Codex CLI
        run: |
          # 替换为官方安装方式/你的镜像源
          curl -fsSL https://.../codex-x86_64-unknown-linux-musl.tar.gz -o codex.tar.gz
          tar -xzf codex.tar.gz
          chmod +x codex
          ./codex --version

      - name: Run Codex Review
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          ./codex review --base main \
            --output-format markdown \
            > /tmp/codex-review.md

      - name: Post Review Comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} --body-file /tmp/codex-review.md

这样每次 PR 推送，Codex 自动出一份结构化审查意见贴在 PR 上 —— 你的 review 从 "人等邮件通知→打开 PR→读 diff→写字" 变成 "AI 先出报告→人只审异常"。

② pre-commit 本地门禁（把垃圾挡在 push 前）

.git/hooks/pre-commit（或走pre-commit.com框架）：

bash

运行

#!/usr/bin/env bash
set -e
echo "🔍  Codex local review gate..."
codex review --uncommitted --sandbox read-only 2>&1 | tee /tmp/pre-commit-review.txt
# 简单策略：如果报告里出现BLOCKING，挡住提交
if grep -q "\[BLOCKING\]" /tmp/pre-commit-review.txt; then
  echo "❌  Blocking issues found — commit rejected. See above."
  exit 1
fi

结语：工程习惯固化为可复用资产

这不是某个孤立工具的配置调整，而是把团队的工程习惯 —— 代码校验、发布门禁、PR 交接 —— 固化成可复现的工程资产：

  • Skill 承载工作流（怎么做）
  • AGENTS.md 声明规则（什么不能做）
  • CI 把同一套流程搬进自动化环境（什么时候跑）

OpenAI 团队用这套方法管自家 SDK 仓库的结果很说明问题（官方叙述）：12 月到次年 2 月，两个仓库 PR 合并量从 316→457（+45%）—— 不是模型更强了，是流程变成了可复用的资产。

下次你打开 PR 窗口，盯着右下角等那个 "LGTM" 时，想一步：今天它读的每一行代码，背后都该有 SKILL.md 和 AGENTS.md 挂着。那些文件才是团队真正的交付加速器。

在 AI 重塑软件开发范式的今天，稳定、高效、低成本的大模型 API 接入是团队技术升级的基础。UseAIAPI 作为专业的全球 AI 大模型接入服务平台，为您的工程效率提升保驾护航：

✅ 全品类主流模型全覆盖：提供 Gemini、Claude、ChatGPT、DeepSeek 等全球热门最新 AI 大模型，一次接入即可畅享全部前沿能力

✅ 企业级定制化服务：提供私有化部署、权限管理、用量监控等专属方案，保障数据安全，让企业无忧直接接入使用

✅ 超值价格优势：优惠折扣最低可达官方价格的 50%，大幅降低高强度代码审查、自动化工作流带来的 token 消耗成本，让您专注工程创新，无需顾虑预算压力

选择 UseAIAPI，让最先进的 AI 能力成为您团队工程效率提升的最强助力。