Codex Migration Guide skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Codex Migration Guide"
  short_description: "Bring your agent setup over without losing rules"
  default_prompt: "$codex-migration-guide We're moving from Claude Code to Codex, port our CLAUDE.md and commands"

# Per-tool conversion details

Read the section for the file type you are converting. Source-tool formats change;
when a source file does not match the shape described here, follow what the file
actually contains and note the difference in the migration report.

## Instruction files

### Codex discovery rules (target behaviour)

- Global: `~/.codex/AGENTS.override.md`, else `~/.codex/AGENTS.md` (first non-empty).
- Project: from the project root (git root by default, see `project_root_markers`)
  down to the working directory; per directory Codex takes the first of
  `AGENTS.override.md`, `AGENTS.md`, then names in `project_doc_fallback_filenames`.
- Files are concatenated root first; closer files come later and win on conflict.
- Total size capped by `project_doc_max_bytes` (32 KiB default).
- Rebuilt at the start of every run or TUI session; restart after editing.

### CLAUDE.md family

| Source | Target | Notes |
|---|---|---|
| `./CLAUDE.md` | `./AGENTS.md` | Move content; drop tool-specific tool names and mode names |
| `./sub/CLAUDE.md` | `./sub/AGENTS.md` | Keep only what differs from the parent |
| `CLAUDE.local.md` (personal, ignored) | `AGENTS.override.md`, git-ignored | An ignored `AGENTS.override.md` is copied into Codex-managed worktrees automatically. Note: an override replaces `AGENTS.md` in that directory rather than adding to it, so copy the shared content in or keep personal notes in `~/.codex/AGENTS.md` instead |
| `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` | Personal defaults across repos |
| `@path/to/file` import lines | Inline the essentials; link the rest | No include directive is documented for AGENTS.md |

### Cursor rules

| Source | Target |
|---|---|
| `.cursorrules` (legacy single file) | Root `AGENTS.md` |
| `.cursor/rules/*.mdc` with always-apply set | Root `AGENTS.md` (merge, dedupe) |
| `.mdc` scoped by globs to a directory tree | `AGENTS.md` inside that directory |
| `.mdc` scoped by globs to a file type across the repo (e.g. `**/*.sql`) | A short section in root `AGENTS.md` ("When editing SQL files: ..."), or a skill if long |
| `.mdc` applied when the agent judges it relevant (description-based) | A skill whose `description` carries the same trigger |
| `.mdc` applied only when manually referenced | Explicit-only skill |

Strip the `.mdc` frontmatter; Codex does not read it.

### Other single-file instructions

`.github/copilot-instructions.md`, `.windsurfrules`, `GEMINI.md`, `CONVENTIONS.md`:
merge into `AGENTS.md`, or list them in `project_doc_fallback_filenames` as a temporary
bridge (only read where no `AGENTS.md` exists in that directory).

## Commands and skills

### Slash-command markdown files

Typical source features and their Codex treatment:

| Source feature | Codex skill equivalent |
|---|---|
| File name = command name | Skill folder name = `name:` in frontmatter |
| Frontmatter description | `description:` rewritten as "does X. Use when Y." |
| Argument placeholder (`$ARGUMENTS`, `$1`) | `## Inputs` section; the agent reads values from the message |
| Inline shell execution markers | Explicit step: "Run `<command>` and use its output" |
| File-inclusion markers | Explicit step: "Read `<path>` first" |
| Per-command tool allowlist | Not enforced by skills; use sandbox/rules for hard limits |
| Per-command model override | Not in SKILL.md; mention a recommended model, or use a profile |

Make command-style skills explicit-only:

```yaml
# .agents/skills/<name>/agents/openai.yaml
policy:
  allow_implicit_invocation: false
```

### Existing SKILL.md folders

Skills follow the open agent skills format, so most folders copy across:

```bash
mkdir -p .agents/skills && cp -R .claude/skills/<name> .agents/skills/
```

Then: remove frontmatter keys other than `name`, `description` (and `license` or other
keys your team standardizes on), fix any hard-coded paths to the old skills directory
in scripts, and run each script once. Personal skills go to `~/.agents/skills/`.

## MCP servers

JSON (`mcpServers` object) to TOML:

```json
{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } },
  "docs": { "type": "http", "url": "https://mcp.example.com/mcp" } } }
```

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env_vars = ["GITHUB_TOKEN"]          # forward from the environment; don't paste the token

[mcp_servers.docs]
url = "https://mcp.example.com/mcp"
# bearer_token_env_var = "DOCS_TOKEN"   # if it uses a bearer token
```

Or: `codex mcp add github --env GITHUB_TOKEN="$GITHUB_TOKEN" -- npx -y @modelcontextprotocol/server-github`
(this writes the literal value into config; prefer `env_vars` for secrets). OAuth
servers: `codex mcp login <name>`. Useful extras: `startup_timeout_sec` (default 10),
`tool_timeout_sec` (default 60), `enabled_tools`, `required = true` for servers a job
cannot run without.

## Permissions

| Source intent | Codex |
|---|---|
| Default ask-before-edit mode | `sandbox_mode = "read-only"`, `approval_policy = "on-request"` |
| Accept edits automatically, ask for risky commands | `sandbox_mode = "workspace-write"`, `approval_policy = "on-request"` |
| Allow specific commands without asking | Inside the sandbox they already run; outside: `prefix_rule(..., decision = "allow")` |
| Deny specific commands | `prefix_rule(..., decision = "forbidden", justification = "...")` |
| Deny reading secret files | Permission profile `"**/*.env" = "deny"` |
| Skip all permission checks | `--sandbox danger-full-access` only inside an isolated container |

Prefix rules match argument prefixes and live in `rules/` next to a config layer
(`~/.codex/rules/`, trusted `<repo>/.codex/rules/`). Test with `codex execpolicy check`.

## Hooks

Codex reads `~/.codex/hooks.json`, `<repo>/.codex/hooks.json` (trusted projects) or
inline `[hooks]` tables. Events include `SessionStart`, `UserPromptSubmit`,
`PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`,
`SubagentStart`, `SubagentStop`, `Stop`. Matchers: `Bash` (shell), `apply_patch` or
`Edit|Write` (file edits), `mcp__server__tool`. New or changed hooks must be trusted
(`/hooks`) before they run. Hook input and output JSON fields differ between tools:
re-test every script against the Codex hooks reference.

## Subagents

Markdown agent definitions become TOML files:

```toml
# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer focused on correctness, security and missing tests."
model_reasoning_effort = "high"
developer_instructions = """
Review like an owner. Do not edit files. Cite file and line for every finding.
"""
```

Custom agents inherit the parent's sandbox, approvals, provider and MCP servers; those
keys in an agent file are ignored. Per-agent tool lists from the source tool do not
carry over except via `features.shell_tool = false` and similar feature switches.