Codex install path and invocation docs are missing, so Atlas is installed for Claude Code but not usable in Codex

[BlakeBatten]

Summary

The README says Atlas works with Claude, Codex, and Gemini, but the current one-line installer and install docs only install the skill into Claude Code's skill directory:

~/.claude/skills/prd-taskmaster
~/.claude/skills/atlas

In Codex, this leaves the user unable to invoke $atlas or /atlas, because Codex discovers skills from:

~/.codex/skills

Also, /atlas appears to be Claude Code slash-command wording. In Codex, the expected user-facing trigger is a Codex skill trigger such as $atlas or natural language like "use atlas", once an atlas skill exists under ~/.codex/skills.

Reproduction

On WSL / Linux with Codex available:

1. Clone or install the repo using the documented installer.
2. Confirm the installer succeeds.
3. Open Codex.
4. Try $atlas or /atlas.

Observed:

• The installer has created files under ~/.claude/skills/....
• Codex does not discover those skills.
• $atlas is unavailable until a separate Codex skill is installed under ~/.codex/skills.
• /atlas remains misleading for Codex because it is Claude Code-style invocation syntax.

Expected:

• A Codex user should be able to follow the README and get a usable Atlas entrypoint in Codex.
• The docs should distinguish Claude Code slash-command usage from Codex skill usage.

Local workaround that worked

Installing the repo root as a Codex skill and adding a small Codex-native alias fixed discovery:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo anombyte93/prd-taskmaster \
  --path . \
  --name prd-taskmaster \
  --dest ~/.codex/skills

Then add ~/.codex/skills/atlas/SKILL.md:

---
name: atlas
description: Use when the user asks for Atlas, the Atlas engine, prd-taskmaster, PRD-to-task workflows, task-driven builds, or says they want to use Atlas in Codex. This is a Codex alias for the prd-taskmaster skill installed from anombyte93/prd-taskmaster.
---

# Atlas

This is a Codex-native alias for the installed `prd-taskmaster` skill.

When this skill triggers:

1. Read `~/.codex/skills/prd-taskmaster/SKILL.md`.
2. Follow that skill's workflow, adapting Claude Code-specific command wording to Codex where needed.
3. Use the local engine script at `~/.codex/skills/prd-taskmaster/script.py` for deterministic operations.

Useful smoke test:

```bash
python3 ~/.codex/skills/prd-taskmaster/script.py engine-preflight

Validation passed locally:

```bash
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/atlas
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ~/.codex/skills/prd-taskmaster
python3 ~/.codex/skills/prd-taskmaster/script.py engine-preflight

engine-preflight returned "ok": true and selected the native backend with codex-cli detected.

Proposed publisher-side solution

1. Update README.md Quickstart to split Claude Code and Codex installation:

# Claude Code
curl -fsSL https://atlas-ai.au/install | bash
# then use /atlas

# Codex
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo anombyte93/prd-taskmaster \
  --path . \
  --name prd-taskmaster \
  --dest ~/.codex/skills
# restart Codex, then use $prd-taskmaster or $atlas if alias is installed

2. Add first-class Codex support to install.sh, for example:

bash install.sh --target claude
bash install.sh --target codex
bash install.sh --target both

For --target codex, install to ${CODEX_HOME:-$HOME/.codex}/skills/prd-taskmaster and create ${CODEX_HOME:-$HOME/.codex}/skills/atlas/SKILL.md.

3. Make invocation docs product-specific:

• Claude Code: /atlas
• Codex: $atlas or "use atlas" after restarting Codex

4. Consider adding a small dedicated Codex alias skill to the repo, or generating it from install.sh, so the advertised Atlas brand entrypoint works consistently across products.

Why this matters

The current behavior looks like a successful install but produces a non-functional Codex experience. Because the installer exits successfully and creates a real /atlas alias under ~/.claude, users can reasonably assume Atlas is installed correctly while Codex still cannot see it.

[anombyte93]

AI work-order (generated via issue-from-feedback). The reporter's bug is reproduced and confirmed against the actual installer. The "Fix Approaches" below are hints, not a spec — the receiving agent should try the recommended path and let does it actually discover in Codex be the source of truth. Acceptance Criteria are the real spec.

Problem

The README advertises "works with Claude · Codex · Gemini", but the documented one-line installer only installs the skill into Claude Code's skill directory. A Codex user who follows the README ends up with no usable Atlas entrypoint in Codex, and /atlas is Claude-Code slash-command wording that doesn't apply to Codex. (Reported by @BlakeBatten — confirmed.)

Current Behavior (verified in the repo)

• install.sh is headed "Universal Claude Code Skill Installer" and hard-codes Claude-only targets:
  • SKILL_DIR="${HOME}/.claude/skills/prd-taskmaster"
  • ALIAS_DIR="${HOME}/.claude/skills/atlas"
  • There is no ~/.codex/skills branch anywhere in the script.
• README.md Installation section offers only Claude paths: curl -fsSL https://atlas-ai.au/install | bash (runs the Claude-only install.sh) and /plugin install prd (a Claude Code plugin command). No Codex install steps; no distinction between Claude /atlas and Codex invocation.
• Codex discovers skills from ~/.codex/skills/<name>/SKILL.md; after the documented install, nothing exists there, so $atlas / "use atlas" is unavailable.

Expected Behavior

• A Codex user following the README gets a discoverable Atlas entrypoint under ~/.codex/skills (the prd-taskmaster skill + an atlas alias).
• Docs clearly separate Claude Code usage (/atlas, /plugin install prd) from Codex usage ($atlas or natural language "use atlas"; skills live in ~/.codex/skills).

Files to Touch

• install.sh — add a Codex install target (detect/offer ~/.codex/skills; install the skill + atlas alias there). Today it only writes ~/.claude/skills/....
• README.md — Installation section (the curl … | bash + /plugin install prd block): add Codex install instructions and a Claude-vs-Codex invocation table.
• (new) skel/codex/atlas/SKILL.md (or similar) — ship the Codex atlas alias template in-repo so the installer can drop it in (content below, from the reporter's working workaround).

Researched Fix Approaches

1. [Recommended] Multi-harness install.sh — detect ~/.claude and ~/.codex, install to each (confidence: 90%)

• Pattern: Parameterize the install target. Auto-detect: if ~/.codex exists install the Codex entrypoint; if ~/.claude exists install the Claude one; add explicit flags --claude / --codex / --all (default: install for every harness detected, prompt if ambiguous).
• Codex install: copy the repo skill into ~/.codex/skills/prd-taskmaster/ and write ~/.codex/skills/atlas/SKILL.md (alias). If the Codex system skill-installer is present (~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py), prefer delegating to it for parity with how the user installs other Codex skills.
• Why: one installer, one source of truth; mirrors the existing Claude alias pattern (ALIAS_NAME="atlas"). Grounded in the reporter's verified workaround.
• Risk: Codex script.py/path assumptions differ from Claude; the alias must point at the Codex-installed prd-taskmaster path, and any /atlas→$atlas wording inside the skill must be adapted for Codex.

2. [Alternative] Docs-first: keep install.sh Claude-only, document the Codex path in README (confidence: 80%)

• Pattern: Add a "Install for Codex" subsection using the system installer:

  python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo anombyte93/prd-taskmaster --path . --name prd-taskmaster --dest ~/.codex/skills

  then drop in the ~/.codex/skills/atlas/SKILL.md alias.
• Why not recommended: leaves the curl one-liner misleading for Codex users (they still hit the gap before reaching the subsection); ships the fix as copy-paste rather than automation.

3. [Fallback] Separate install-codex.sh (confidence: 65%)

• Pattern: A dedicated Codex installer invoked by a second curl line.
• Why last resort: two installers drift; the multi-harness single script (Approach 1) is cleaner.

Reference

• Reporter's working workaround (this is the proof the fix is viable): install the repo root as a Codex skill via the system installer, then add ~/.codex/skills/atlas/SKILL.md:

  ---
  name: atlas
  description: Use when the user asks for Atlas, the Atlas engine, prd-taskmaster, PRD-to-task workflows, task-driven builds, or says they want to use Atlas in Codex. Codex alias for the prd-taskmaster skill from anombyte93/prd-taskmaster.
  ---
  # Atlas
  Codex-native alias for the installed `prd-taskmaster` skill. On trigger: read `~/.codex/skills/prd-taskmaster/SKILL.md`, follow its workflow (adapting Claude Code command wording to Codex), and use `~/.codex/skills/prd-taskmaster/script.py` for deterministic operations.

• Codex skill discovery convention: ~/.codex/skills/<name>/SKILL.md; system installer at ~/.codex/skills/.system/skill-installer/.

Acceptance Criteria

• Following ONLY the README, a Codex user ends up with ~/.codex/skills/prd-taskmaster/SKILL.md and ~/.codex/skills/atlas/SKILL.md, discoverable by Codex (no manual workaround needed).
• install.sh installs the Codex entrypoint when Codex is present, is idempotent/upgrade-safe, and still installs the Claude entrypoint unchanged when Claude is present.
• README Installation section distinguishes Claude (/atlas, /plugin install prd, ~/.claude/skills) from Codex ($atlas / "use atlas", ~/.codex/skills) — e.g. a small two-column table.
• Smoke test: in a fresh Codex session after install, $atlas (or "use atlas") triggers the skill and reaches the engine entrypoint.
• No regression: existing Claude Code install path and /atlas continue to work.

Complexity: M

Trust Level: HINT (not specification)

1. Confirm how Codex resolves skill triggers by inspecting an existing working Codex skill under ~/.codex/skills/ (e.g. atlas-review, start) — match that structure, don't assume.
2. Verify the system skill-installer's actual flags before scripting against it (install-skill-from-github.py --help).
3. Try Approach 1; if Codex doesn't discover the skill, inspect a known-good Codex skill rather than retrying blindly.
4. The Acceptance Criteria — does Codex actually trigger $atlas — are the real spec, not the wording above.

---

_{Enriched from the original report via issue-from-feedback. Grounded in the repo's actual install.sh + the local Codex skill convention rather than web research, since this is an installer/docs issue where the codebase is the source of truth.}

[anombyte93]

Gemini parity (extending the work-order above)

The README advertises Gemini too, and the install gap applies there as well — but Gemini's skill mechanism is different again from both Claude and Codex:

• Discovery: Gemini CLI loads skills via the skillz extension at ~/.gemini/extensions/skillz/ (skills are activated on demand through the activate_skill tool / GEMINI.md) — not ~/.gemini/skills, not ~/.codex/skills, not ~/.claude/skills.
• Invocation: Gemini users trigger a skill via activate_skill or natural language ("use atlas") — not /atlas (Claude slash-command) and not $atlas (Codex).

So the recommended multi-harness install.sh (Approach 1) should detect a third target — ~/.gemini — and install the Atlas skill where the skillz extension reads it, then ensure it is activatable.

Add to "Files to Touch": install.sh (Gemini target branch), README.md (Gemini row in the invocation table).

The docs invocation table should cover all three harnesses:

Harness	Skills location	Trigger
Claude Code	~/.claude/skills/	/atlas
Codex	~/.codex/skills/	$atlas / "use atlas"
Gemini CLI	~/.gemini/extensions/skillz/ (via activate_skill)	"use atlas" / activate_skill atlas

Add to Acceptance Criteria:

• A Gemini user following the README ends up with a discoverable Atlas skill activatable via activate_skill / "use atlas" (no manual step), and the README distinguishes the Gemini trigger from /atlas and $atlas.

Trust (Gemini): verify the EXACT path the skillz extension reads skills from (inspect ~/.gemini/extensions/skillz/) before scripting — do not assume ~/.gemini/skills.