AI Agent / 系统课时
创建可复用 Skills
创建可复用 Skills
当同一套仓库检查、发布准备或代码生成规则反复出现时,反复粘贴长提示既容易漂移,也难维护。本课把流程封装成一个可被 Codex 发现、触发并复用的 Skill,并用脚本承载需要确定执行的步骤。
学习目标
- 理解
SKILL.md、脚本、参考资料和资源文件各自承担的职责 - 编写触发范围清晰、步骤可执行的 Skill
- 在仓库级目录中创建、验证并迭代一个可复用 Skill
Skill 的最小组成
一个 Skill 本质上是一个目录,入口必须是 SKILL.md;它可以再带 scripts/、references/、assets/,以及可选的 agents/openai.yaml。Codex 先利用 name 和 description 判断是否匹配任务,真正选中后再读取完整说明,需要时才继续取用脚本或参考资料。:contentReference[oaicite:0]{index=0}

SKILL.md 的 frontmatter 至少写 name 与 description。其中 description 不只是介绍文字,它直接影响隐式触发,所以应同时说明“做什么”和“什么时候用”,并尽量给出边界,避免一个 Skill 抢走无关任务。
创建一个仓库发布检查 Skill
下面把“发布前检查关键文件”做成仓库级 Skill。示例把工作流说明留在 SKILL.md,把机械、可重复的文件检查放进 Bash 脚本;这样既能让 Codex理解意图,又能让关键判断稳定执行。
mkdir -p .agents/skills/release-check/scripts
cat > .agents/skills/release-check/SKILL.md <<'EOF'
---
name: release-check
description: Use when preparing a repository release and checking whether required release files are present. Do not use for normal feature development.
---
# Release Check
Before preparing a release:
1. Run `scripts/check-release.sh` against the repository root.
2. Stop if the script reports a missing required file.
3. If the precheck passes, review the changelog for release notes and report any unresolved release blockers.
EOF
cat > .agents/skills/release-check/scripts/check-release.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
target="${1:-.}"
required=(package.json CHANGELOG.md)
for file in "${required[@]}"; do
if [[ ! -f "$target/$file" ]]; then
echo "MISSING $file"
exit 1
fi
echo "OK $file"
done
echo "release precheck passed"
EOF
chmod +x .agents/skills/release-check/scripts/check-release.sh
demo_dir="$(mktemp -d)"
touch "$demo_dir/package.json" "$demo_dir/CHANGELOG.md"
.agents/skills/release-check/scripts/check-release.sh "$demo_dir"
rm -rf "$demo_dir"预期输出
OK package.json
OK CHANGELOG.md
release precheck passed这个示例刻意没有把所有判断都塞进脚本。需要理解上下文、阅读变更或形成结论的步骤更适合保留为指令;只有要求结果稳定、失败条件明确的动作才值得脚本化。
让 Codex 发现并触发
仓库级 Skill 放在 .agents/skills 下即可。Codex 会从当前工作目录向仓库根目录扫描这些目录;个人通用 Skill 可以放在 $HOME/.agents/skills,共享机器上的管理员 Skill 可放在 /etc/codex/skills。在 Codex CLI 或 IDE 中可以通过 /skills 查看可用 Skill,也可以输入 $release-check 显式调用。:contentReference[oaicite:1]{index=1}
修改 Skill 后 Codex通常会自动检测变化;若列表没有更新,再重启会话或 Codex。测试时至少准备两类请求:一类明确应该触发,例如“检查这个仓库是否可以发版”;另一类明确不该触发,例如“实现一个搜索框”。如果后者也命中,应先收窄 description,而不是继续往正文里堆限制。
保持 Skill 可维护
一个 Skill 最好只解决一个稳定目标。长背景材料放到 references/,让正文只保留决策和执行步骤;需要复制到最终产物的模板、图标或样板文件放到 assets/;只有确实需要确定性或外部工具时才增加脚本。
当一个流程准备分享给更多人时,可以把 Skill 作为插件中的 skills/ 内容分发;本地仓库目录更适合快速迭代。最终验收标准不是“文件齐全”,而是代表性请求能稳定触发、脚本失败能阻断错误流程、无关请求不会被误匹配。