---
title: "迁移自定义提示到新机制"
description: "说明 custom prompts 弃用后，如何把可复用 instructions 迁移到 Codex skills。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 8 分钟换什么**：把"custom prompts → skills"的迁移从一次性替换重新理解成**按用途三分类**——临时个人话术留为 prompt，稳定工作流升级为 skill，团队分发能力打包成 plugin。读完后你不会一刀切删除旧 prompt，也不会把所有东西都迁成 skill。

Custom prompts 已 deprecated。可复用 instructions 推荐使用 [skills](https://developers.openai.com/codex/skills)，因为 skills 可以由 Codex 显式或隐式调用。

```mermaid
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](https://developers.openai.com/codex/skills)。

## 先判断迁移到哪里

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

| 类型 | 推荐去向 | 判断标准 |
| --- | --- | --- |
| 临时个人快捷语 | 继续保留为 prompt | 只给自己用，只需要 slash command 显式触发，不需要随项目共享。 |
| 稳定工作流 | 迁移到 skill | 需要 Codex 根据任务自动识别，或需要附带 scripts、references、assets。 |
| 团队分发能力 | 迁移到 plugin 中的 skill | 希望其他开发者安装，或要把 skill 和 app/MCP 配置一起打包。 |

如果一个 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 调用。

最小结构如下：

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

`SKILL.md` 的最小写法：

```markdown
---
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：

```bash
mkdir -p ~/.codex/prompts
```

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

```markdown
---
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，并解析参数标记。

| 字段/占位 | 说明 |
| --- | --- |
| **Description** | 在 popup 的 command name 下显示。用 YAML front matter 中的 `description:` 设置。 |
| **Argument hint** | 用 `argument-hint: KEY=<value>` 说明预期 parameters。 |
| **Positional 参数标记** | `$1` 到 `$9` 会从 command 后的 space-separated arguments 展开。`$ARGUMENTS` 包含全部 positional arguments。 |
| **Named 参数标记** | 使用 `$FILE` 或 `$TICKET_ID` 这类 uppercase names，并通过 `KEY=value` 传值。有空格的值要 quote，例如 `FOCUS="loading state"`。 |
| **Literal dollar signs** | 写 `$$` 可以在 expanded prompt 中输出单个 `$`。 |

编辑 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：

```text
/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](https://developers.openai.com/codex/skills)
- [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)
- [Build Codex plugins](https://developers.openai.com/codex/plugins/build)

## 接下来去哪

<Cards>
  <Card title="Skills 复用" href="/docs/codex/official/03-extensions/09-skills-reuse" description="迁过去之后怎么写好一个 skill" />
  <Card title="构建 Plugins" href="/docs/codex/official/03-extensions/69-build-plugins" description="团队分发用的 plugin 打包流程" />
  <Card title="Plugins 管理" href="/docs/codex/official/03-extensions/68-plugins-manage" description="安装 / 升级 / 移除 plugin" />
  <Card title="CLI Slash 命令" href="/docs/codex/official/01-products/25-cli-slash" description="保留下来的旧 prompt 仍走这里" />
  <Card title="自定义行为" href="/docs/codex/official/02-config-security/48-customize-behavior" description="把 skill / prompt 与配置统一编排" />
</Cards>
