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 从触发元数据到脚本与资源的渐进式加载关系

SKILL.md 的 frontmatter 至少写 name 与 description。其中 description 不只是介绍文字,它直接影响隐式触发,所以应同时说明“做什么”和“什么时候用”,并尽量给出边界,避免一个 Skill 抢走无关任务。

创建一个仓库发布检查 Skill

下面把“发布前检查关键文件”做成仓库级 Skill。示例把工作流说明留在 SKILL.md,把机械、可重复的文件检查放进 Bash 脚本;这样既能让 Codex理解意图,又能让关键判断稳定执行。

bash
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"

预期输出

text
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/ 内容分发;本地仓库目录更适合快速迭代。最终验收标准不是“文件齐全”,而是代表性请求能稳定触发、脚本失败能阻断错误流程、无关请求不会被误匹配。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建可复用 Skills

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通