OpenSpec installs Codex skills into the legacy .codex/skills #1509

init/update install Codex skills into the legacy .codex/skills instead of the canonical .agents/skills

Type

Bug (integration targets a directory OpenAI has deprecated for Codex CLI)

Environment

Summary

openspec init (and openspec update) writes the Codex workflow skills to
<project>/.codex/skills/openspec-*/SKILL.md. Per OpenAI's current Codex CLI
documentation and an OpenAI maintainer's own statement, .codex/skills is the
legacy location; the canonical, documented path is .agents/skills.

The result is that OpenSpec's Codex integration is generated into a directory
that OpenAI documents as unsupported and recommends migrating away from.

Steps to reproduce

1. Fresh project directory, no .codex/ and no .agents/ present.
2. Run openspec init.
3. Select Claude Code and Codex in the tool picker.
4. Inspect the generated tree.

Actual behavior

$ openspec init
...
OpenSpec Setup Complete

Created: Codex
Refreshed: Claude Code
6 skills and 6 commands in .codex, .claude/
Commands skipped for: codex (uses skills)

$ fd . .codex
.codex/skills/openspec-apply-change/SKILL.md
.codex/skills/openspec-archive-change/SKILL.md
.codex/skills/openspec-explore/SKILL.md
.codex/skills/openspec-propose/SKILL.md
.codex/skills/openspec-sync-specs/SKILL.md
.codex/skills/openspec-update-change/SKILL.md

Nothing is written under .agents/skills.

Expected behavior

The codex target should generate into <project>/.agents/skills/openspec-*/SKILL.md,
with existing OpenSpec-managed .codex/skills/openspec-* directories migrated
(and non-OpenSpec content under .codex/ left untouched).

Evidence

1. OpenSpec source

src/core/config.ts (line 30 on main at time of writing):

{ name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },

All skill paths are built as path.join(projectPath, tool.skillsDir, 'skills')
(src/core/update.ts), so this single field is what produces .codex/skills.

For contrast, the shared target added in #1303 already points at the canonical
directory (line 63):

{ name: 'Shared .agents skills', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'] }

2. OpenAI's Codex CLI documentation

https://learn.chatgpt.com/docs/build-skills (the current target of the 308 redirect
from https://developers.openai.com/codex/skills/) lists the discovery locations as:

• $CWD/.agents/skills
• $CWD/../.agents/skills
• $REPO_ROOT/.agents/skills
• $HOME/.agents/skills
• /etc/codex/skills (admin)
• bundled system skills

Verbatim: "Codex reads skills from repository, user, admin, and system locations.
For repositories, Codex scans .agents/skills in every directory from your current
working directory up to the repository root."

.codex/skills is not documented as a discovery location at any scope.

3. OpenAI maintainer statement

openai/codex#14337, comment by @etraut-openai (2026-03-11):

~/.codex/skills is the old (legacy) name. The industry has since standardized
on ~/.agents/skills. We recommend moving to this directory, which is why the
documentation reflects this.

Link: openai/codex#14337 (comment)

Scope note — what is and isn't verified

Being precise so the severity isn't overstated:

• Verified: .agents/skills is the only documented Codex skills path, and an
  OpenAI maintainer calls .codex/skills legacy and recommends migrating off it.
• Verified: OpenSpec 1.7.0 and current main still write the codex target to .codex/skills.
• Known undocumented-but-working: the reporter of "Skills" installed locations is missing .codex/skills openai/codex#14337 observed
  that Codex CLI does still pick up skills from ~/.codex/skills (user scope).
  So this is a deprecated-path bug, not necessarily a hard "skills never load" bug.

Proposed fix

1. Change the codex entry's skillsDir from .codex to .agents.
2. Register .codex as a legacy skills dir for that target so OpenSpec-managed
   openspec-* directories are migrated on init/update, going through the
   edited-file-preserving migration framework rather than a bespoke cleanup path.
3. Leave any non-OpenSpec content under .codex/ alone.
4. Reconcile with the agents target from feat(init): add shared agents skills target #1303 so selecting both Codex and the
   shared .agents target converges on one directory instead of duplicating skills.
5. Update the supported-tools docs and the post-init summary line accordingly.

Prior art in this repo

• PR feat(codex): migrate .codex skills to .agents #1157 — feat(codex): migrate .codex skills to .agents — did exactly
  this. Closed unmerged on 2026-08-04 by @clay-good: "Closing this exact branch,
  not rejecting the direction of consolidating Codex skills." Reasons given: the
  branch was ~115 commits behind/conflicting, predated the skills-only Codex work
  in feat(codex): make Codex skills-only and retire managed custom prompts #1283, and its custom cleanup should be rebuilt on the edited-file-preserving
  migration framework.
• PR feat(codex): make Codex skills-only and retire managed custom prompts #1283 — made Codex skills-only and retired managed custom prompts (merged).
• PR feat(init): add shared agents skills target #1303 / issue Feedback: Please implement the 'agents' tool target (.agents/skills + .agents/commands). It is registered in the tool list as available:false with no skillsDir, so AGENTS.md-based setups have to generate for another tool and move files by hand. #1480 — added the shared agents target writing to
  .agents/skills (merged 2026-07-29, after the 1.7.0 release, so not yet
  available in the published CLI).
• Issue Proposal: use a standard .agent/skills folder for all agents that support it #689 — earlier proposal for a standard shared skills folder (closed).

Filing this so the direction #1157 was closed on has a tracking issue that isn't
tied to a stale branch. Happy to open a rebased PR if a maintainer confirms the
intended shape — in particular whether codex should point at .agents directly
or delegate to the agents target. [FILL] keep or drop this offer.