feat(codex): install BMAD as Codex custom prompts#1890
Closed
LINGREN201 wants to merge 1 commit intobmad-code-org:mainfrom
Closed
feat(codex): install BMAD as Codex custom prompts#1890LINGREN201 wants to merge 1 commit intobmad-code-org:mainfrom
LINGREN201 wants to merge 1 commit intobmad-code-org:mainfrom
Conversation
📝 WalkthroughWalkthroughThis PR transitions Codex from Native Skills (.agents/skills) to Slash Commands (.codex/prompts), introduces manifest-based artifact installation from skill-manifest.csv, and adds multi-target synchronization for BMAD artifacts across project and home directories. Documentation and tests are updated throughout. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🧹 Nitpick comments (3)
test/test-installation-components.js (2)
597-630: Add a regression for preserving unrelated files in~/.codex/prompts.The new sync path mutates the user's home prompt directory, but this test only proves BMAD files show up there. Seed the temp home dir with one unrelated prompt and one foreign
bmad-*prompt, then assert setup does not delete files it does not own.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@test/test-installation-components.js` around lines 597 - 630, The test should be updated to seed tempHome11 with unrelated and foreign bmad-* prompt files before calling IdeManager.setup so the sync step doesn't delete files it doesn't own; create an unrelated prompt (e.g., writeFile(path.join(tempHome11, '.codex', 'prompts', 'unrelated.md'), '...')) and a foreign bmad file (e.g., 'bmad-foreign.md'), then after calling ideManager11.setup('codex', ...) assert that both of those files still exist (use fs.pathExists on their paths) in addition to the existing assertions that globalPrompt11 and globalHelpPrompt11 exist and that legacyDir11 was removed; reference the test variables tempHome11, globalPrompt11, globalHelpPrompt11 and the method IdeManager.setup to locate where to add the setup and final assertions.
57-63: This fixture does not model the prompt-path contract being tested.
skill-manifest.csvsays_bmad/core/tasks/bmad-help/SKILL.md, but the fixture createscore/tasks/bmad-help/SKILL.mdoutside the temp project. The generated Codex prompt can therefore point at a nonexistent project path and this suite will still pass.Also applies to: 88-97
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@test/test-installation-components.js` around lines 57 - 63, The fixture's manifest and created SKILL.md path are inconsistent: the CSV written to path.join(fixtureDir, '_config', 'skill-manifest.csv') lists "_bmad/core/tasks/bmad-help/SKILL.md" but the test creates "core/tasks/bmad-help/SKILL.md", so update the fixture so the on-disk file path matches the manifest (or vice versa) to model the prompt-path contract; specifically align the entry in 'skill-manifest.csv' with the actual created file (or change the created file under fixtureDir to "_bmad/core/tasks/bmad-help/SKILL.md"), and apply the same fix for the other instance noted around lines 88-97 so both manifest entries and created SKILL.md locations are consistent.tools/cli/installers/lib/ide/templates/combined/default-skill.md (1)
10-11: Add an already-loaded guard to the recursive file-following step.This prompt now blindly follows referenced files with no idempotency rule, so
SKILL.md -> workflow.md -> SKILL.mdcycles are possible. Add a “do not reload files already opened in this activation” guard or equivalent bounded wording.Based on learnings: future edits to
default-*.mdtemplates should add loop-prevention and idempotent step semantics.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tools/cli/installers/lib/ide/templates/combined/default-skill.md` around lines 10 - 11, The recursive file-following step (the lines "Follow all instructions in the skill file exactly as written." and "If the skill references additional files (for example `workflow.md`), load and follow those as well.") needs an idempotency/loop-prevention guard: modify that section to explicitly track and skip files already opened in this activation (e.g., "do not reload files already opened in this activation") or otherwise bound recursion depth; ensure the wording enforces not reopening any filename/ID encountered earlier in the same activation so SKILL.md -> workflow.md -> SKILL.md cycles are prevented and the step semantics remain idempotent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/how-to/non-interactive-installation.md`:
- Around line 66-67: The docs currently imply two independent locations for
Codex prompts; update the wording to make clear that BMAD writes the
project-local `.codex/prompts` during setup and then syncs/overwrites (mirrors)
that content to `~/.codex/prompts`, so `~/.codex/prompts` is not an independent
editable target — manual edits there will be replaced by BMAD syncs; reference
the `.codex/prompts` and `~/.codex/prompts` paths and mention the Codex CLI
examples (`/prompts:bmad-help`, `/prompts:bmad-master`) remain usable but
originate from the project-local source.
In `@docs/zh-cn/how-to/non-interactive-installation.md`:
- Around line 66-67: 请修改文档中关于 codex 的描述，明确说明项目内的 `.codex/prompts` 会被同步（镜像）到用户主目录
`~/.codex/prompts`，且主目录下的文件只是一个受控的同步副本（不是独立来源），因此对 `~/.codex/prompts`
的手动编辑会被覆盖或不同步；保留示例调用
`/prompts:bmad-help`、`/prompts:bmad-master`，并在同段落或括注中加入一句简短警告，提示用户应在项目的
`.codex/prompts` 中进行永久修改而非直接在 `~/.codex/prompts` 中修改。
In `@README_CN.md`:
- Around line 50-55: The README_CN section shows installing with --tools codex
but still leads with the legacy CLI help command /bmad-help; update the Chinese
text to lead with the Codex prompt format by replacing the initial mention of
"/bmad-help" with "/prompts:bmad-help" (and update the example phrase
"/bmad-help 我刚刚完成了架构设计，接下来该做什么？" to use "/prompts:bmad-help
我刚刚完成了架构设计，接下来该做什么？") so the guidance aligns with the installed --tools codex
usage.
In `@tools/cli/installers/lib/ide/_config-driven.js`:
- Around line 794-806: The cleanup currently blindly removes any entry starting
with "bmad" which can delete other projects' prompts; modify the pruning logic
in the sync/remove code paths (around resolveTargetPath and ensureDir usage) to
first detect ownership before deleting: either (A) write/read a small ownership
marker (e.g., ".bmad-owner" containing a unique project identifier or
sourcePath) into the target directory when creating/mirroring prompts and only
remove bmad* entries whose marker matches the current project, or (B) if entries
are symlinks, resolve the symlink target and only remove entries that point back
to this sync's sourcePath; apply the same change to the other cleanup occurrence
mentioned (lines ~886-890) so deletions are scoped to owned entries only.
- Around line 741-769: The loop that creates skill artifacts should skip records
whose source path is missing or points to a non-existent SKILL.md to avoid
emitting broken bmad-*.md prompts; in installVerbatimSkills (the records loop
that computes relativePath, artifact, content, filename and calls
writeFile/generateFilename/renderTemplate) check that record.path is present and
that the expected source file exists (e.g. path.join(record.path, 'SKILL.md') or
the resolved relativePath target) before rendering/generating the prompt—if the
file is missing, continue the loop and do not increment count or write the
output.
- Around line 886-890: The current flow calls cleanupTarget for each
installerConfig.sync_targets before prompt generation, which can delete the
mirrored home prompts if later installation steps fail; change the flow so
cleanup() / cleanupTarget does not remove the live mirrored prompts until the
new prompts are successfully generated and installed—either move the loop that
calls cleanupTarget to after the successful install/generation step, or modify
cleanupTarget/cleanup() to perform a safe staged cleanup (e.g., remove temporary
artifacts first and only replace/delete the existing mirror after write
succeeds). Update references: installerConfig.sync_targets, cleanupTarget, and
cleanup() accordingly.
- Around line 710-719: The parser currently accepts any CSV header which can
hide malformed manifests; update loadSkillManifestRecords to validate the header
of skill-manifest.csv before returning parsed rows: after reading csvContent (or
by parsing with a relaxed option), extract the header fields from the first line
and compare them against the expected header set (define an expected array of
column names used elsewhere in this module, e.g., the names referenced by
downstream code that consumes the manifest). If the header is missing required
columns or contains unexpected/misordered names, throw an Error that includes
the csvPath and a clear message about the missing/invalid columns; only if the
header passes validation proceed to call csv.parse(...) with columns: true and
return the records. Use the existing function name loadSkillManifestRecords and
csvPath/ csvContent variables to locate where to implement this check.
In `@tools/cli/installers/lib/ide/platform-codes.yaml`:
- Around line 79-80: The YAML currently sets a global home-directory sync target
("sync_targets" includes "~/.codex/prompts"), which must not be enabled by
default; remove or empty the default entry for sync_targets in
platform-codes.yaml and instead provide an opt-in mechanism or commented example
showing how a user can add "~/.codex/prompts" themselves (e.g., keep a
documented example under sync_targets but do not include the actual home path as
a live default). Update any installer logic that relies on sync_targets to treat
an empty or missing list as "no home sync" and only perform the global write
when the user explicitly configures the path.
In `@tools/docs/native-skills-migration-checklist.md`:
- Line 35: Update the checklist item to require deterministic cleanup/overwrite
semantics for BMAD-owned global files instead of merely warning: replace the
"warnings" phrasing and change the task to explicitly verify that upgrades
either overwrite or remove BMAD-managed files in ~/.codex/prompts and
project-local .agents/skills (and document the exact deterministic behavior),
and ensure the checklist references verifying ownership detection and safe
atomic replace/remove operations so stale global commands cannot persist.
- Line 34: Add a delete path for manifest-driven outputs so removed canonicalIds
listed in skill-manifest.csv are cleaned up on reinstall: when reading
skill-manifest.csv (e.g., entries like `bmad-help`) compare the current emitted
prompt-command files/records against the new manifest set and remove any
artifacts whose canonicalId is no longer present; implement this in the same
pipeline stage that emits manifest entries so it runs on install/reinstall and
ensure the removal honors idempotency and error handling for missing files.
- Around line 36-37: Update the two checklist items "Test fresh install" and
"Test reinstall/upgrade from legacy skills output" to require running those
tests with a clean isolated HOME/workspace so leftover prompts in
~/.codex/prompts can't be picked up; document that testers must run the
install/upgrade steps with HOME (or the workspace root) pointed at an empty temp
directory (e.g., export HOME=/tmp/empty_home or equivalent CI job isolation) and
verify ~/.codex/prompts is absent before validating results.
- Around line 33-39: Add a documented manual CLI verification step to the
checklist: instruct reviewers to run a versioned `codex` command (e.g., `codex
--version && codex list` or similar) to confirm the CLI lists all skills, verify
that `bmad-help` appears and can be triggered, and confirm artifacts sync to
`.codex/prompts` and `~/.codex/prompts` while ensuring ancestor conflict
protection for inherited `.codex/prompts`; add this as a new checklist item
alongside the existing entries so the migration checklist explicitly includes
the manual CLI repro step.
- Line 29: Update the checklist entry that currently states "Support assumption:
Codex custom slash commands are file-based prompts. BMAD targets
`.codex/prompts` and syncs to `~/.codex/prompts` for Codex discovery" to reflect
that Codex supports the Agent Skills (SKILL.md) format: either change the
guidance to require migrating Codex outputs to native Agent Skills format
(ensure tooling described in the checklist includes creating SKILL.md and
placing skills where Codex will discover them) or explicitly mark Codex as an
intentional exception by replacing the line with a short rationale and link to
OpenAI's Codex documentation showing SKILL.md support and explain why
`.codex/prompts` should remain allowed; reference the `.codex/prompts` string
and SKILL.md in your update so reviewers can locate and verify the change.
- Line 10: Update the line that currently reads "`Codex CLI` now uses
`.codex/prompts` slash commands (not Agent Skills format)" to clarify BMAD's
choice: reword it to state that BMAD configures Codex to use `.codex/prompts`
prompt artifacts instead of Agent Skills format while leaving support for Agent
Skills intact (mention that Codex still supports Agent Skills via `SKILL.md`
under `.agents/skills` and user/admin/system locations); ensure the new phrasing
mirrors the suggested text such as "BMAD configures Codex to use
`.codex/prompts` prompt artifacts instead of Agent Skills format" so it
accurately reflects the intent.
---
Nitpick comments:
In `@test/test-installation-components.js`:
- Around line 597-630: The test should be updated to seed tempHome11 with
unrelated and foreign bmad-* prompt files before calling IdeManager.setup so the
sync step doesn't delete files it doesn't own; create an unrelated prompt (e.g.,
writeFile(path.join(tempHome11, '.codex', 'prompts', 'unrelated.md'), '...'))
and a foreign bmad file (e.g., 'bmad-foreign.md'), then after calling
ideManager11.setup('codex', ...) assert that both of those files still exist
(use fs.pathExists on their paths) in addition to the existing assertions that
globalPrompt11 and globalHelpPrompt11 exist and that legacyDir11 was removed;
reference the test variables tempHome11, globalPrompt11, globalHelpPrompt11 and
the method IdeManager.setup to locate where to add the setup and final
assertions.
- Around line 57-63: The fixture's manifest and created SKILL.md path are
inconsistent: the CSV written to path.join(fixtureDir, '_config',
'skill-manifest.csv') lists "_bmad/core/tasks/bmad-help/SKILL.md" but the test
creates "core/tasks/bmad-help/SKILL.md", so update the fixture so the on-disk
file path matches the manifest (or vice versa) to model the prompt-path
contract; specifically align the entry in 'skill-manifest.csv' with the actual
created file (or change the created file under fixtureDir to
"_bmad/core/tasks/bmad-help/SKILL.md"), and apply the same fix for the other
instance noted around lines 88-97 so both manifest entries and created SKILL.md
locations are consistent.
In `@tools/cli/installers/lib/ide/templates/combined/default-skill.md`:
- Around line 10-11: The recursive file-following step (the lines "Follow all
instructions in the skill file exactly as written." and "If the skill references
additional files (for example `workflow.md`), load and follow those as well.")
needs an idempotency/loop-prevention guard: modify that section to explicitly
track and skip files already opened in this activation (e.g., "do not reload
files already opened in this activation") or otherwise bound recursion depth;
ensure the wording enforces not reopening any filename/ID encountered earlier in
the same activation so SKILL.md -> workflow.md -> SKILL.md cycles are prevented
and the step semantics remain idempotent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c2f0ca4a-8112-4932-8069-eb4b831b36a5
📒 Files selected for processing (9)
README.mdREADME_CN.mddocs/how-to/non-interactive-installation.mddocs/zh-cn/how-to/non-interactive-installation.mdtest/test-installation-components.jstools/cli/installers/lib/ide/_config-driven.jstools/cli/installers/lib/ide/platform-codes.yamltools/cli/installers/lib/ide/templates/combined/default-skill.mdtools/docs/native-skills-migration-checklist.md
Comment on lines
+66
to
+67
| For `codex`, BMAD installs slash-command prompt files into `.codex/prompts` and syncs them to `~/.codex/prompts`. | ||
| Use them in Codex CLI as `/prompts:bmad-help`, `/prompts:bmad-master`, etc. |
There was a problem hiding this comment.
Clarify that ~/.codex/prompts is a mirror, not a second independent install target.
The implementation rewrites the home directory from the project-local .codex/prompts on setup. This wording reads like BMAD manages two independent prompt locations, which will surprise users who expect manual edits in ~/.codex/prompts to survive.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/how-to/non-interactive-installation.md` around lines 66 - 67, The docs
currently imply two independent locations for Codex prompts; update the wording
to make clear that BMAD writes the project-local `.codex/prompts` during setup
and then syncs/overwrites (mirrors) that content to `~/.codex/prompts`, so
`~/.codex/prompts` is not an independent editable target — manual edits there
will be replaced by BMAD syncs; reference the `.codex/prompts` and
`~/.codex/prompts` paths and mention the Codex CLI examples
(`/prompts:bmad-help`, `/prompts:bmad-master`) remain usable but originate from
the project-local source.
Comment on lines
+66
to
+67
| 对于 `codex`，BMAD 会把 slash 命令提示文件安装到 `.codex/prompts`，并同步到 `~/.codex/prompts`。 | ||
| 在 Codex CLI 中用 `/prompts:bmad-help`、`/prompts:bmad-master` 等方式调用。 |
There was a problem hiding this comment.
Clarify in Chinese docs that ~/.codex/prompts is a synced mirror.
Right now this reads like BMAD installs and manages two separate prompt locations. The code actually mirrors the project-local prompts into the home directory, so readers should be warned that manual edits there are not independent.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/zh-cn/how-to/non-interactive-installation.md` around lines 66 - 67,
请修改文档中关于 codex 的描述，明确说明项目内的 `.codex/prompts` 会被同步（镜像）到用户主目录
`~/.codex/prompts`，且主目录下的文件只是一个受控的同步副本（不是独立来源），因此对 `~/.codex/prompts`
的手动编辑会被覆盖或不同步；保留示例调用
`/prompts:bmad-help`、`/prompts:bmad-master`，并在同段落或括注中加入一句简短警告，提示用户应在项目的
`.codex/prompts` 中进行永久修改而非直接在 `~/.codex/prompts` 中修改。
Comment on lines
+50
to
+55
| npx bmad-method install --directory /path/to/project --modules bmm --tools codex --yes | ||
| ``` | ||
|
|
||
| [查看所有安装选项](http://docs.bmad-method.org/how-to/non-interactive-installation/) | ||
|
|
||
| > **不确定该做什么？** 运行 `/bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `/bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。 | ||
| > **不确定该做什么？** 运行 `/bmad-help`（Codex CLI 使用 `/prompts:bmad-help`）— 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `/bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。 |
There was a problem hiding this comment.
Lead with the Codex command form in the Chinese README too.
This section now installs --tools codex, but the next help instruction still starts with /bmad-help. For Codex users, /prompts:bmad-help should be the first command shown here.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README_CN.md` around lines 50 - 55, The README_CN section shows installing
with --tools codex but still leads with the legacy CLI help command /bmad-help;
update the Chinese text to lead with the Codex prompt format by replacing the
initial mention of "/bmad-help" with "/prompts:bmad-help" (and update the
example phrase "/bmad-help 我刚刚完成了架构设计，接下来该做什么？" to use "/prompts:bmad-help
我刚刚完成了架构设计，接下来该做什么？") so the guidance aligns with the installed --tools codex
usage.
Comment on lines
+710
to
+719
| async loadSkillManifestRecords(bmadDir) { | ||
| const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv'); | ||
|
|
||
| if (!(await fs.pathExists(csvPath))) return []; | ||
|
|
||
| const csvContent = await fs.readFile(csvPath, 'utf8'); | ||
| return csv.parse(csvContent, { | ||
| columns: true, | ||
| skip_empty_lines: true, | ||
| }); |
There was a problem hiding this comment.
Validate the skill-manifest.csv header before consuming it.
Codex install now depends on this file, but columns: true will happily parse any header row. If the manifest is stale or malformed, the later code just emits a partial prompt set or silently skips rows instead of failing with a clear error.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/cli/installers/lib/ide/_config-driven.js` around lines 710 - 719, The
parser currently accepts any CSV header which can hide malformed manifests;
update loadSkillManifestRecords to validate the header of skill-manifest.csv
before returning parsed rows: after reading csvContent (or by parsing with a
relaxed option), extract the header fields from the first line and compare them
against the expected header set (define an expected array of column names used
elsewhere in this module, e.g., the names referenced by downstream code that
consumes the manifest). If the header is missing required columns or contains
unexpected/misordered names, throw an Error that includes the csvPath and a
clear message about the missing/invalid columns; only if the header passes
validation proceed to call csv.parse(...) with columns: true and return the
records. Use the existing function name loadSkillManifestRecords and csvPath/
csvContent variables to locate where to implement this check.
Comment on lines
+741
to
+769
| for (const record of records) { | ||
| const canonicalId = record?.canonicalId; | ||
| if (!canonicalId) continue; | ||
|
|
||
| let relativePath = String(record.path || '').replaceAll('\\', '/'); | ||
| if (relativePath.startsWith(bmadPrefix)) { | ||
| relativePath = relativePath.slice(bmadPrefix.length); | ||
| } else if (relativePath.startsWith('_bmad/')) { | ||
| relativePath = relativePath.slice(6); | ||
| } else if (relativePath.startsWith('bmad/')) { | ||
| relativePath = relativePath.slice(5); | ||
| } | ||
|
|
||
| const artifact = { | ||
| type: 'skill', | ||
| name: canonicalId, | ||
| module: record.module || 'core', | ||
| description: record.description || `${canonicalId} skill`, | ||
| path: relativePath, | ||
| relativePath, | ||
| canonicalId, | ||
| }; | ||
|
|
||
| const content = this.renderTemplate(template, artifact); | ||
| const filename = this.generateFilename(artifact, 'skill', extension); | ||
| const filePath = path.join(targetPath, filename); | ||
|
|
||
| await this.writeFile(filePath, content); | ||
| count++; |
There was a problem hiding this comment.
Verify record.path exists before generating a prompt.
installVerbatimSkills() checks the source directory exists; this path does not. A stale manifest row will still produce a bmad-*.md prompt that points at a missing SKILL.md, so setup reports success with a broken command.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/cli/installers/lib/ide/_config-driven.js` around lines 741 - 769, The
loop that creates skill artifacts should skip records whose source path is
missing or points to a non-existent SKILL.md to avoid emitting broken bmad-*.md
prompts; in installVerbatimSkills (the records loop that computes relativePath,
artifact, content, filename and calls writeFile/generateFilename/renderTemplate)
check that record.path is present and that the expected source file exists (e.g.
path.join(record.path, 'SKILL.md') or the resolved relativePath target) before
rendering/generating the prompt—if the file is missing, continue the loop and do
not increment count or write the output.
| ## Codex CLI | ||
|
|
||
| Support assumption: full Agent Skills support. BMAD has already migrated from `.codex/prompts` to `.agents/skills`. | ||
| Support assumption: Codex custom slash commands are file-based prompts. BMAD targets `.codex/prompts` and syncs to `~/.codex/prompts` for Codex discovery. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Read the native-skills-migration-checklist.md file to understand scope and context
cat -n tools/docs/native-skills-migration-checklist.mdRepository: bmad-code-org/BMAD-METHOD
Length of output: 21009
🌐 Web query:
Codex Agent Skills support OpenAI documentation
💡 Result:
OpenAI Codex supports “Agent Skills” (the open SKILL.md-based skills format) across the Codex CLI, IDE extension, and Codex app, and documents how skills are discovered, invoked (explicit $skill-name / /skills and implicit by description), installed ($skill-installer), and enabled/disabled via ~/.codex/config.toml. [1]
Official / primary docs:
- OpenAI Codex Agent Skills documentation (how skills work in Codex):
developers.openai.com/codex/skills[1] - Agent Skills open specification (SKILL.md format, required fields, optional dirs, etc.):
agentskills.io/specification[2] - OpenAI’s reference skills catalog (examples you can install/learn from):
github.com/openai/skills[3] - Codex product overview (mentions Skills as a core feature):
openai.com/codex[4]
Sources
- OpenAI Codex docs — Agent Skills [1]
- Agent Skills — Specification [2]
- GitHub —
openai/skills[3] - OpenAI — Codex product page [4]
Codex should migrate to Agent Skills format or be explicitly documented as an intentional exception.
The checklist's scope requires platforms to "fully support the Agent Skills standard," but Codex is described as using .codex/prompts slash commands instead. OpenAI's official Codex documentation confirms Codex fully supports the Agent Skills (SKILL.md) format for discovery, invocation, and installation. Either migrate Codex output to native Agent Skills format to align with the checklist scope, or document this as a deliberate prompt-based exception with explicit reasoning for why Codex should remain outside the standard Agent Skills migration path.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/docs/native-skills-migration-checklist.md` at line 29, Update the
checklist entry that currently states "Support assumption: Codex custom slash
commands are file-based prompts. BMAD targets `.codex/prompts` and syncs to
`~/.codex/prompts` for Codex discovery" to reflect that Codex supports the Agent
Skills (SKILL.md) format: either change the guidance to require migrating Codex
outputs to native Agent Skills format (ensure tooling described in the checklist
includes creating SKILL.md and placing skills where Codex will discover them) or
explicitly mark Codex as an intentional exception by replacing the line with a
short rationale and link to OpenAI's Codex documentation showing SKILL.md
support and explain why `.codex/prompts` should remain allowed; reference the
`.codex/prompts` string and SKILL.md in your update so reviewers can locate and
verify the change.
Comment on lines
+33
to
39
| - [x] Confirm current implementation matches Codex CLI prompt command expectations | ||
| - [x] Ensure skill-manifest entries (for example `bmad-help`) are also emitted as prompt commands | ||
| - [x] Confirm legacy cleanup for prior project-local `.agents/skills` output and global `~/.codex/prompts` warnings | ||
| - [x] Test fresh install | ||
| - [x] Test reinstall/upgrade from legacy prompt output | ||
| - [x] Confirm ancestor conflict protection because Codex inherits parent-directory `.agents/skills` | ||
| - [x] Test reinstall/upgrade from legacy skills output | ||
| - [x] Confirm ancestor conflict protection because Codex can inherit parent-directory `.codex/prompts` | ||
| - [x] Implement/extend automated tests as needed |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "native-skills-migration-checklist.md" -type fRepository: bmad-code-org/BMAD-METHOD
Length of output: 118
🏁 Script executed:
cat -n ./tools/docs/native-skills-migration-checklist.mdRepository: bmad-code-org/BMAD-METHOD
Length of output: 21009
🏁 Script executed:
# Check if there's any documentation about manual verification elsewhere in the repo
find . -type f -name "*.md" | xargs grep -l "Codex" | head -10Repository: bmad-code-org/BMAD-METHOD
Length of output: 296
🏁 Script executed:
# Let me check for any actual test files or evidence of Codex testing
find . -type f \( -name "*test*" -o -name "*spec*" \) | xargs grep -l -i "codex" 2>/dev/null | head -5Repository: bmad-code-org/BMAD-METHOD
Length of output: 107
🏁 Script executed:
grep -A 20 -B 5 -i "codex" ./test/test-installation-components.jsRepository: bmad-code-org/BMAD-METHOD
Length of output: 6092
🏁 Script executed:
# Check how other sections document their manual verification (like Crush)
grep -B 2 -A 2 "Manual CLI verification" ./tools/docs/native-skills-migration-checklist.mdRepository: bmad-code-org/BMAD-METHOD
Length of output: 830
🏁 Script executed:
# Final check: look at the openai/codex package to understand if it's actively maintained
curl -s https://registry.npmjs.org/@openai/codex 2>/dev/null | head -50 || echo "Cannot access npm registry"Repository: bmad-code-org/BMAD-METHOD
Length of output: 50383
Add documented manual CLI verification for Codex — this section is marked complete but lacks the manual CLI verification step that comparable platforms (Crush, Gemini CLI) include. Since Codex switches artifact models to .codex/prompts, syncs to ~/.codex/prompts, and is actively released with frequent upgrades, a versioned manual CLI repro should be documented (e.g., codex lists all skills and successfully triggers bmad-help) to match the verification rigor applied to other volatile platforms.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/docs/native-skills-migration-checklist.md` around lines 33 - 39, Add a
documented manual CLI verification step to the checklist: instruct reviewers to
run a versioned `codex` command (e.g., `codex --version && codex list` or
similar) to confirm the CLI lists all skills, verify that `bmad-help` appears
and can be triggered, and confirm artifacts sync to `.codex/prompts` and
`~/.codex/prompts` while ensuring ancestor conflict protection for inherited
`.codex/prompts`; add this as a new checklist item alongside the existing
entries so the migration checklist explicitly includes the manual CLI repro
step.
| - [x] Confirm current implementation still matches Codex CLI skills expectations | ||
| - [x] Confirm legacy cleanup for project and global `.codex/prompts` | ||
| - [x] Confirm current implementation matches Codex CLI prompt command expectations | ||
| - [x] Ensure skill-manifest entries (for example `bmad-help`) are also emitted as prompt commands |
There was a problem hiding this comment.
You’re missing the delete path for manifest-driven output.
This verifies that manifest entries are emitted, but not that removed canonicalIds disappear on reinstall. That stale-file case is the regression most likely to bite this pipeline because skill-manifest.csv is now the source of truth.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/docs/native-skills-migration-checklist.md` at line 34, Add a delete
path for manifest-driven outputs so removed canonicalIds listed in
skill-manifest.csv are cleaned up on reinstall: when reading skill-manifest.csv
(e.g., entries like `bmad-help`) compare the current emitted prompt-command
files/records against the new manifest set and remove any artifacts whose
canonicalId is no longer present; implement this in the same pipeline stage that
emits manifest entries so it runs on install/reinstall and ensure the removal
honors idempotency and error handling for missing files.
| - [x] Confirm legacy cleanup for project and global `.codex/prompts` | ||
| - [x] Confirm current implementation matches Codex CLI prompt command expectations | ||
| - [x] Ensure skill-manifest entries (for example `bmad-help`) are also emitted as prompt commands | ||
| - [x] Confirm legacy cleanup for prior project-local `.agents/skills` output and global `~/.codex/prompts` warnings |
There was a problem hiding this comment.
“Warnings” is not enough for a home directory BMAD writes into.
If BMAD syncs prompts to ~/.codex/prompts, upgrades need deterministic overwrite/removal semantics for BMAD-owned files. A warning-only check leaves stale global commands behind and makes behavior depend on whatever a user happened to install previously.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/docs/native-skills-migration-checklist.md` at line 35, Update the
checklist item to require deterministic cleanup/overwrite semantics for
BMAD-owned global files instead of merely warning: replace the "warnings"
phrasing and change the task to explicitly verify that upgrades either overwrite
or remove BMAD-managed files in ~/.codex/prompts and project-local
.agents/skills (and document the exact deterministic behavior), and ensure the
checklist references verifying ownership detection and safe atomic
replace/remove operations so stale global commands cannot persist.
Comment on lines
36
to
+37
| - [x] Test fresh install | ||
| - [x] Test reinstall/upgrade from legacy prompt output | ||
| - [x] Confirm ancestor conflict protection because Codex inherits parent-directory `.agents/skills` | ||
| - [x] Test reinstall/upgrade from legacy skills output |
There was a problem hiding this comment.
Fresh-install and upgrade tests need a clean HOME.
Because this section says BMAD also syncs to ~/.codex/prompts, a nominal “fresh install” or “upgrade” can pass by accidentally picking up leftover home-level prompts. Require an isolated HOME/workspace for these checks, otherwise the checklist can validate the wrong target.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tools/docs/native-skills-migration-checklist.md` around lines 36 - 37, Update
the two checklist items "Test fresh install" and "Test reinstall/upgrade from
legacy skills output" to require running those tests with a clean isolated
HOME/workspace so leftover prompts in ~/.codex/prompts can't be picked up;
document that testers must run the install/upgrade steps with HOME (or the
workspace root) pointed at an empty temp directory (e.g., export
HOME=/tmp/empty_home or equivalent CI job isolation) and verify ~/.codex/prompts
is absent before validating results.
Collaborator
|
We've been there, wasted a lot of time maintaining the installer. From now on it's all skills all the way. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Why
How
Testing