Skip to content

fix(speckit-pro): install Codex skills in .agents/skills and keep .codex/skills as legacy - #635

Merged
fgabelmannjr merged 2 commits into
mainfrom
fix/codex-skills-dual-path
Sep 25, 2026
Merged

fix(speckit-pro): install Codex skills in .agents/skills and keep .codex/skills as legacy#635
fgabelmannjr merged 2 commits into
mainfrom
fix/codex-skills-dual-path

Conversation

@fgabelmannjr

@fgabelmannjr fgabelmannjr commented Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

The install and upgrade skills told operators that SpecKit puts Codex skills in
.codex/skills/. SpecKit writes them to .agents/skills/, and the upgrade
snapshot never backed that directory up. This change makes .agents/skills/
the primary Codex skills path and keeps .codex/skills/ as a legacy path that
Codex still reads.

  • Install (both mirrors): name .agents/skills/speckit-*/ as the Codex
    path. Drop the redundant --integration-options="--skills" option, because
    skills mode is the Codex default. Report a legacy .codex/skills/ directory
    and leave it in place.
  • Upgrade (both mirrors): the snapshot now copies .agents/skills/ as well
    as .claude/, .codex/, and .github/, so Codex skills are backed up from
    whichever path exists. The dedupe step checks both skills paths against the
    legacy .codex/prompts/speckit.*.md files.
  • gh-stack trust roots: the stack manager now also trusts
    ~/.agents/skills/gh-stack/SKILL.md, the current Codex user skills root,
    next to ~/.claude/skills and the legacy ~/.codex/skills. The pinned
    digest check is unchanged.
  • Docs: the first-run page shows the plain Codex init command.
  • Evals: the Codex Layer 3 install and upgrade evals now expect the dual
    path. Expectation counts and order are unchanged, so the catalog mappings
    still line up.

Evidence

  • SpecKit v0.4.0 moved Codex from prompt files in .codex/ to native skills in
    .agents/skills/ ("feat: migrate Codex/agy init to native skills workflow",
    feat: migrate Codex/agy init to native skills workflow github/spec-kit#1906, CHANGELOG [0.4.0]).
  • The pinned v0.8.13 writes .agents/skills/speckit-<name>/SKILL.md, and its
    --skills option defaults to true
    (src/specify_cli/integrations/codex/__init__.py, lines 3, 33-39, and 65-69).
    v1.0.1 and v1.0.11 are the same.
  • No SpecKit release wrote Codex skills to .codex/skills/. Codex CLI itself
    still reads a project .codex/skills/ root (codex-rs/ext/skills/src/host_roots.rs
    in openai/codex), so the skills keep it as a legacy
    location.

Testing

  • New Layer 1 checks in validate-skill-contracts.py: both install mirrors
    name .agents/skills/ as primary, every .codex/skills/ mention is marked
    legacy, and both upgrade mirrors snapshot and dedupe both paths.
  • New unit check in test-stack-manager-plan.py for the trusted skill roots.
  • python3 scripts/refresh-release-artifacts.py and
    pnpm --dir docs-site reference:generate regenerated the artifacts.
  • The default suite gate passes, and ruff and mypy are clean.

Release note

The speckit-install and speckit-upgrade skills now point Codex skills at
`.agents/skills/`, where SpecKit writes them. They still treat a legacy
`.codex/skills/` directory as valid. Upgrades now back up `.agents/skills/`
before changing anything.

https://claude.ai/code/session_01TKYXGuzRL9QJFYPJrbHr5z

@fgabelmannjr
fix(speckit-pro): install Codex skills in .agents/skills and keep .co…
c7bba9f 
…dex/skills as legacy

SpecKit writes Codex skills to .agents/skills (since v0.4.0, github/spec-kit#1906; the
pinned v0.8.13 and 1.x do the same), but the install and upgrade skills
named .codex/skills and the upgrade snapshot never backed up
.agents/skills.

- Install mirrors name .agents/skills/speckit-*/ as the primary Codex
  path, drop the redundant --integration-options="--skills" (skills mode
  is the Codex default), and treat .codex/skills/ as legacy.
- Upgrade mirrors snapshot .agents/skills/ and dedupe against both
  skills paths.
- The gh-stack trust roots add ~/.agents/skills next to the legacy
  ~/.codex/skills.
- The first-run docs page and the Codex Layer 3 install and upgrade
  evals follow the dual path.
- New Layer 1 and unit checks cover the dual-path wording and trust
  roots.

Claude-Session: https://claude.ai/code/session_01TKYXGuzRL9QJFYPJrbHr5z
@fgabelmannjr fgabelmannjr changed the title fix/codex skills dual path fix(speckit-pro): install Codex skills in .agents/skills and keep .codex/skills as legacy Sep 24, 2026
@fgabelmannjr
fgabelmannjr marked this pull request as ready for review September 24, 2026 20:45
Copilot AI lite review requested due to automatic review settings September 24, 2026 20:45
@fgabelmannjr
fgabelmannjr requested a review from a team as a code owner September 24, 2026 20:45
Copilot AI reviewed Sep 24, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The changes consistently implement the primary/legacy Codex skills path behavior across skills, tests, evals, docs, and regenerated artifacts without introducing correctness or contract issues.

Review effort: Lite
Findings: None

What changed in this PR

No blocking issues. 0 important, 0 nits.

This PR corrects the Codex skills installation/upgrade guidance and related validation so it matches SpecKit’s actual Codex skills location (.agents/skills/), while continuing to support .codex/skills/ as a legacy path that Codex still reads.

Changes:

  • Update install/upgrade skill instructions to treat .agents/skills/ as the primary Codex skills root and .codex/skills/ as legacy.
  • Expand upgrade snapshot/dedupe guidance and eval expectations to handle both primary and legacy Codex skills paths.
  • Extend gh-stack trusted user-skill roots to include ~/.agents/skills (alongside existing roots) and add/adjust tests and contracts accordingly.
File Description
tests/​speckit-pro/​unit/​test-stack-manager-plan.py Adds unit coverage for trusted Codex user skill roots (primary + legacy).
tests/​speckit-pro/​layer3-functional/​codex-evals/​speckit-upgrade-evals.json Updates eval expectations for dual-path Codex skill backup/dedupe.
tests/​speckit-pro/​layer3-functional/​codex-evals/​speckit-install-evals.json Updates eval expectations to prefer .agents/skills/ and allow legacy.
tests/​speckit-pro/​layer1-structural/​validate-skill-contracts.py Adds structural checks enforcing primary/legacy Codex skills wording and steps.
speckit-pro/​speckit_pro_runner/​speckit-pro-runner.sha256 Refreshes runner hash for updated stack manager helper.
speckit-pro/​speckit_pro_runner/​speckit-pro-runner.manifest.json Refreshes manifest sha256 for updated stack manager helper.
speckit-pro/​speckit_pro_runner/​helpers/​stack_manager.py Trusts ~/.agents/skills in addition to existing trusted skill roots.
speckit-pro/​skills/​speckit-upgrade/​SKILL.md Documents backing up/deduping Codex skills across primary + legacy paths.
speckit-pro/​skills/​speckit-install/​SKILL.md Documents .agents/skills/ as primary Codex skills path; legacy noted.
speckit-pro/​codex-skills/​speckit-upgrade/​SKILL.md Mirrors upgrade guidance for Codex-facing skill variant.
speckit-pro/​codex-skills/​speckit-install/​SKILL.md Mirrors install guidance for Codex-facing skill variant.
docs-site/​src/​content/​docs/​first-run.md Updates Codex init command to the default skills-mode invocation.
dist/​codex/​speckit-pro/​speckit_pro_runner/​speckit-pro-runner.sha256 Regenerated distribution artifact hash.
dist/​codex/​speckit-pro/​speckit_pro_runner/​speckit-pro-runner.manifest.json Regenerated distribution manifest entry.
dist/​codex/​speckit-pro/​speckit_pro_runner/​helpers/​stack_manager.py Regenerated distribution helper output.
dist/​codex/​speckit-pro/​skills/​speckit-upgrade/​SKILL.md Regenerated distribution skill output.
dist/​codex/​speckit-pro/​skills/​speckit-install/​SKILL.md Regenerated distribution skill output.
dist/​claude/​speckit-pro/​speckit_pro_runner/​speckit-pro-runner.sha256 Regenerated distribution artifact hash.
dist/​claude/​speckit-pro/​speckit_pro_runner/​speckit-pro-runner.manifest.json Regenerated distribution manifest entry.
dist/​claude/​speckit-pro/​speckit_pro_runner/​helpers/​stack_manager.py Regenerated distribution helper output.
dist/​claude/​speckit-pro/​skills/​speckit-upgrade/​SKILL.md Regenerated distribution skill output.
dist/​claude/​speckit-pro/​skills/​speckit-install/​SKILL.md Regenerated distribution skill output.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@fgabelmannjr
fgabelmannjr merged commit dc949a2 into main Sep 25, 2026
28 checks passed
@fgabelmannjr
fgabelmannjr deleted the fix/codex-skills-dual-path branch September 25, 2026 00:14
@fgabelmannjr fgabelmannjr mentioned this pull request Sep 25, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@fgabelmannjr