# Codex Skill 编写模板

核验日期：2026-07-16

## 适合做成 Skill 的流程

- 会重复发生。
- 输入、步骤、输出和验证相对稳定。
- 需要说明、references 或确定性脚本。
- 不只是某一次任务的业务需求。

仓库共享 skill 放在 `.agents/skills/<name>/`，个人跨仓库 skill 放在 `$HOME/.agents/skills/<name>/`。

## 目录

```text
.agents/skills/review-ready/
├── SKILL.md
├── references/
│   └── finding-severity.md
└── scripts/
    └── verify-diff.sh
```

先从只有 `SKILL.md` 的 instruction-only 版本开始。只有流程需要确定性行为时才增加脚本。

## 可用 SKILL.md 示例

```md
---
name: review-ready
description: Prepare a completed code change for review by checking scope, diff hygiene, repository validation, and an evidence-based summary. Use after implementation is finished. Do not use to implement features or publish changes.
---

# Review-ready workflow

## Inputs

- The task goal and acceptance criteria.
- The current Git diff.
- Applicable AGENTS.md files.
- Repository validation commands.

## Steps

1. Read `git status --short` and the full diff.
2. Compare every changed file with the allowed task scope.
3. Stop if unrelated or unexplained changes are present; do not revert them.
4. Run the narrowest relevant checks, then broader required checks.
5. Review correctness, permissions, secrets, error paths and test coverage.
6. Produce the report format below.

## Output

- Goal and scope.
- Changed files with reasons.
- Commands actually run and their exit results.
- Manual QA performed.
- Findings or remaining risks.
- Checks not run and why.

## Boundaries

- Do not commit, push, publish or deploy.
- Do not discard unknown worktree changes.
- Do not describe a command as passed unless it was run in this task.
- Do not expose secrets from environment variables or files.
```

## Description 规则

Codex先看到 name、description 和路径，再决定是否加载完整 `SKILL.md`。因此 description 要：

- 前置最关键触发词。
- 明确何时使用。
- 明确何时不使用。
- 避免“帮助处理代码”等宽泛表述。

## References 与 scripts

- 大篇背景、术语和示例放 `references/`，只在需要时读取。
- 确定性格式检查或重复命令可放 `scripts/`。
- 脚本使用严格错误模式和明确输入。
- 脚本不读取秘密，不执行生产操作，不隐藏失败。
- 在 SKILL.md 中写明何时运行脚本及如何判断结果。

`verify-diff.sh` 的安全起点：

```bash
#!/usr/bin/env bash
set -euo pipefail

git status --short
git diff --check
git diff --stat
```

## 触发测试矩阵

应该触发：

- “实现完成了，帮我准备 review 证据。”
- “检查 diff 范围并整理实际测试结果。”

不应触发：

- “实现新的支付流程。”
- “把分支推到生产。”
- “解释这个函数做什么。”

## 发布前自检

- [ ] name 简短且唯一。
- [ ] description 有正向和负向边界。
- [ ] 一个 skill 只负责一个流程。
- [ ] 步骤使用明确动词、输入和输出。
- [ ] 验证与失败行为清楚。
- [ ] scripts 可单独运行并返回可靠退出码。
- [ ] references 不包含秘密、私有数据或过时事实。
- [ ] 显式调用与隐式匹配都经过测试。
- [ ] 修改后 Codex 能发现新版本；必要时重启会话。

官方来源：

- https://learn.chatgpt.com/docs/build-skills