迁移自定义提示到新机制

Custom prompts 已 deprecated。可复用 instructions 推荐使用 skills，因为 skills 可以由 Codex 显式或隐式调用。

flowchart LR
    Old["📜 旧 custom prompt"]
    Q{"用途是什么？"}
    A["🚀 临时个人快捷语<br/>（一段固定话术）"]
    B["🛠 稳定工作流<br/>（多步 / 检查清单 / 模板）"]
    C["📦 团队分发能力<br/>（要其他人安装）"]
    Keep["保留为 slash prompt"]
    Skill["迁移到 skill"]
    Plugin["打包到 plugin → skill"]
    Old --> Q
    Q -->|个人 / 单段| A --> Keep
    Q -->|多步 / 含资源| B --> Skill
    Q -->|跨人共享| C --> Plugin

Custom prompts 旧机制可以把 Markdown files 变成 reusable prompts，并在 Codex CLI 和 Codex IDE extension 中作为 slash commands 调用。

它有几个限制：

• 需要显式 invocation。
• 存在本地 Codex home directory 中，例如 ~/.codex。
• 不会随 repository 共享。

如果你想分享 prompt，或希望 Codex 根据任务隐式调用，请使用 skills。

先判断迁移到哪里

旧 custom prompt 不一定都要直接删除。迁移前先按用途分三类：

如果一个 prompt 只有一段固定话术，例如“帮我总结最后一次 diff”，继续保留为 slash command 成本最低。

如果它已经包含多步流程、检查清单、输入输出格式、模板或脚本调用，就应该迁移到 skill。官方 skills 机制的定位是 reusable workflows，Codex CLI、IDE extension 和 Codex app 都可以使用。

把旧 prompt 拆成 skill

迁移时不要把整个旧 prompt 原封不动塞进 SKILL.md。更稳的方式是把它拆成四层：

1. 触发条件：写进 YAML front matter 的 description，明确什么时候使用、什么时候不使用。
2. 执行步骤：写成 imperative steps，避免“你可以考虑”这类松散表述。
3. 资源文件：模板、长参考、示例输出放到 references/ 或 assets/。
4. 自动化脚本：确定性处理逻辑放到 scripts/，由 skill instructions 调用。

最小结构如下：

my-workflow/
  SKILL.md
  references/
  assets/
  scripts/

SKILL.md 的最小写法：

---
name: draft-pr-workflow
description: Use when preparing a clean Git branch, commit, and draft pull request from local changes.
---

Follow these steps:

1. Inspect the working tree and identify changed files.
2. Summarize the behavioral change and test coverage.
3. Stage only files relevant to the requested change.
4. Commit with a concise message.
5. Open a draft pull request with summary and verification notes.

迁移后，用一个真实任务触发它。理想结果是你不需要输入旧的 /prompts:* 命令，Codex 看到任务描述就能选择对应 skill；如果 description 太宽，Codex 会误触发；如果太窄，则需要每次显式 $skill-name 调用。

创建自定义提示词

1. 创建 prompts directory：

mkdir -p ~/.codex/prompts

2. 创建 ~/.codex/prompts/draftpr.md，写入 reusable guidance：

---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---

为这次工作创建一个名为 `dev/<feature_name>` 的 branch。
如果指定了 files，请先 stage 它们：$FILES。
用清楚的 commit message 提交 staged changes。
在同一 branch 上打开 draft PR。如果提供了 $PR_TITLE，请使用它；否则自己写一个简洁 summary。

3. 重启 Codex，让它加载 new prompt。CLI 需要 restart session；如果使用 IDE extension，需要 reload extension。

预期结果：在 slash command menu 中输入 /prompts:draftpr，会看到这个 custom command。command 下方显示 front matter 中的 description，并提示 files 和 PR title 是 optional。

添加元数据和参数

Codex 会在下次 session start 时读取 prompt metadata，并解析参数标记。

编辑 prompt files 后，重启 Codex 或打开 new chat，updates 才会加载。Codex 会忽略 prompts directory 中的 non-Markdown files。

调用和管理自定义命令

调用方式：

1. 在 Codex，也就是 CLI 或 IDE extension 中，输入 / 打开 slash command menu。
2. 输入 prompts: 或 prompt name，例如 /prompts:draftpr。
3. 提供 required arguments：

/prompts:draftpr FILES="src/pages/index.astro src/lib/api.ts" PR_TITLE="Add hero animation"

4. 按 Enter 发送 expanded instructions。不需要某个 argument 时可以省略。

预期结果：Codex 会展开 draftpr.md 的内容，把参数标记替换成你提供的 arguments，然后把结果作为 message 发送。

管理方式：编辑或删除 ~/.codex/prompts/ 下的 files。

Codex 只扫描该 folder 顶层的 Markdown files。因此，每个 custom prompt 都要直接放在 ~/.codex/prompts/ 下，不要放在 subdirectories 中。

迁移后的检查清单

迁移完成后，按这几个点验收：

• Slash command 仍能调用：输入 / 后可以看到旧 prompt，或确认旧 prompt 已经被删除。
• Skill 能被发现：Codex 启动时 available skills 列表里有新 skill，必要时重启 Codex。
• 触发边界清楚：相邻任务不会误触发，新任务也不用复制大段 prompt。
• 项目共享正确：团队级 workflow 放在 repo .agents/skills，个人 workflow 放在用户 skills 目录。
• 大段背景不挤占上下文：长 reference 放到文件里，由 skill 按需读取。

常见错误

• 只把旧 prompt 改名成 SKILL.md，没有写清 description。这样 Codex 很难自动选择。
• 把所有个人命令都迁移成 skill。一次性话术保留为 custom prompt 更简单。
• 把团队 workflow 放进 ~/.codex/prompts/。旧 prompt 不随 repo 共享，其他人不会自动获得。
• 删除旧 prompt 前没有保留一轮回退。建议先并行保留一段时间，确认 skill 触发稳定后再删。

官方资料

• Agent Skills
• Slash commands in Codex CLI
• Build Codex plugins

接下来去哪