docs(codex): add symlink install guide for git-pull upgrades#587
docs(codex): add symlink install guide for git-pull upgrades#587yuanxiao0115 wants to merge 4 commits intoEveryInc:mainfrom
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5a698bb1e6
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| If you previously installed CE skills by copying into `~/.codex/skills`, remove the copied CE directories so the symlinked source is authoritative: | ||
|
|
||
| ```bash | ||
| rm -rf ~/.codex/skills/ce-* |
There was a problem hiding this comment.
This migration command does not match the stated goal of removing copied Compound Engineering skills: rm -rf ~/.codex/skills/ce-* only deletes ce-* folders, but the Codex conversion installs all plugin skills (see skillDirs = copiedSkills.map(...) in src/converters/claude-to-codex.ts), including many non-ce-* names (for example proof, todo-create, and others). Users who follow this step will keep stale CE skill copies in ~/.codex/skills, so the symlinked repo is not actually authoritative and outdated duplicates can still be discovered.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed.
The migration step no longer uses rm -rf ~/.codex/skills/ce-*.
It now uses cleanup-codex-copied-skills.py, which derives the full Codex copy target set from current CE skill metadata (name +
ce_platforms) and Codex name normalization (: -> -), so it covers non-ce-* skills as well (for example proof, todo- create, etc.).
By default it runs in --dry-run, and --apply performs deletion.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eadd223bb2
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| target = target_skills_root / name | ||
| if not target.exists() and not target.is_symlink(): | ||
| continue | ||
|
|
||
| if dry_run: |
There was a problem hiding this comment.
This migration script deletes ~/.codex/skills/<name> purely by matching directory names derived from current CE metadata, but it never verifies that the target actually came from Compound Engineering before calling unlink/rmtree. Since the computed list includes generic names (for example proof, onboarding, changelog), a user who has unrelated skills with the same names will lose them when running this command; please check each target's SKILL.md provenance (or require explicit confirmation) before deletion.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed.
I updated scripts/cleanup-codex-copied-skills.py to verify ownership before any deletion. For each candidate under ~/.codex/ skills/<name>, it now checks:
SKILL.mdexists- frontmatter
namematches the expected CE skill name SKILL.mdcontent matches the current CE source skill file
If verification fails, the target is skipped by default (skipped_unverified).
Deleting unverified targets now requires explicit opt-in: --apply --force-unverified.
| If you previously installed CE skills by copying into `~/.codex/skills`, run the cleanup script to derive exact Codex copy targets from current `skills/*/SKILL.md` metadata (`name` + `ce_platforms`) and remove only those copied CE skill directories: | ||
|
|
||
| ```bash | ||
| python3 scripts/cleanup-codex-copied-skills.py |
There was a problem hiding this comment.
The migration step invokes python3 scripts/cleanup-codex-copied-skills.py, but the install flow never instructs users to cd into the cloned repository first. Following the guide verbatim from another working directory makes this command fail with a missing-file error, so users can unintentionally skip the cleanup; the doc should either add a cd ~/.codex/compound-engineering-plugin step or use the full script path.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Good catch — addressed.
I updated the cleanup commands to use the clone-absolute script path:
python3 ~/.codex/compound-engineering-plugin/scripts/cleanup-codex-copied-skills.py --dry-runpython3 ~/.codex/compound-engineering-plugin/scripts/cleanup-codex-copied-skills.py --apply
So the migration flow no longer depends on running from the repository root.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d93ee28ead
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| ```bash | ||
| mkdir -p ~/.agents/skills | ||
| ln -s ~/.codex/compound-engineering-plugin/plugins/compound-engineering/skills ~/.agents/skills/compound-engineering |
There was a problem hiding this comment.
This command links the whole plugins/compound-engineering/skills tree as a single entry (~/.agents/skills/compound-engineering), but Codex skill discovery expects each child under the skills root to be a skill directory with its own SKILL.md (the same one-level layout our loader enforces in src/parsers/claude-home.ts via <skillsDir>/<entry>/SKILL.md). In that setup, compound-engineering itself has no SKILL.md, so users following these steps can restart Codex and still have no CE skills discovered; the install flow should link individual skill folders (or use plugin packaging) instead of a nested bundle directory.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Thanks for the review.
I believe this comment is based on an assumption that is stricter than the current Codex docs.
According to the official docs, Codex scans .agents/skills across repo hierarchy ($CWD/.agents/skills, $CWD/../.agents/skills,
$REPO_ROOT/.agents/skills) and explicitly supports symlinked skill folders:
https://developers.openai.com/codex/skills
Given that behavior, linking the CE skills source and relying on Codex discovery is intentional here, and has been validated locally
(skills are discovered after restart).
If maintainers still prefer per-skill links for readability/explicitness, I can update the guide accordingly, but this is not a hard
functional requirement per the official docs.
|
I replied in-thread with the rationale and doc reference: Given the documented discovery behavior (including parent-folder scanning and symlinked skill folders), this PR keeps the current Would appreciate a human review decision on this point. Thanks. |
|
Thanks for the contribution and welcome! We are overhauling how we install so may need to take a pause on this while we figure this out. So leaving open for now... |
2 participants
• ## Summary
This PR adds a Codex-native install path for Compound Engineering that supports straightforward
git pullupgrades.What changed
.codex/INSTALL.mdwith a clone + symlink workflow for Codex native skill discovery.~/.codex/skills/ce-*) to a symlinked source-of-truth setup.README.mdto.codex/INSTALL.mdfor users who prefer the git-based upgrade path..gitignoreto keep.codexignored by default while explicitly tracking.codex/INSTALL.md.Why
The converted install flow is convenient, but copied skills can make updates harder to reason about.
This guide provides a repo-linked workflow so CE skill updates can be pulled with
git pull, with explicit install, verify, update,and uninstall steps.
Validation