migrate-agents-to-codex

Name: migrate-agents-to-codex
Author: zuharz

60stars6forks

How to install migrate-agents-to-codex?

zuharz/ccode-to-codex/migrate-agents-to-codex

$npx -y skills add zuharz/ccode-to-codex --skill migrate-agents-to-codex

Installs into the current project.

Summary

Migrate Claude agent definitions (.claude/agents/*.md) to Codex-compatible markdown or TOML outputs under .codex/agents/. Strips frontmatter, maps fields to native Codex contracts, normalizes MCP namespaces, and classifies agents into 3 tiers. Includes adversarial cross-model r

Files · 1

View on GitHub

SKILL.md

1	<!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. -->
2	# Migrate Agents to Codex
3
4	## Purpose
5
6	Migrates Claude agent definitions from `.claude/agents/*.md` (YAML frontmatter
7	+ markdown body) to Codex-compatible outputs under `.codex/agents/`.
8
9	Preferred output: standalone TOML custom-agent files.
10	Backward-compatible output only: pure-markdown behavioral specifications.
11
12	The migration strips frontmatter, maps fields to native Codex contracts,
13	preserves runtime hints such as `model`, `effort`, `reasoning_effort`, and
14	`model_reasoning_effort`, normalizes MCP namespaces, and extracts large domain
15	content into companion reference files.
16
17	After migration, a native Codex compliance audit (GPT-5.4 inline
18	sub-agent) validates every migrated file passes as a native Codex sub-agent —
19	not a ported Claude artifact. Mechanical output is never final on write alone:
20	every mechanically generated agent requires a recorded manual nativeness review
21	before it may be treated as native. Findings are auto-addressed and a
22	convergence check confirms no regressions were introduced by the fixes.
23
24	Pipeline position: CODE → VERIFY (runs during implementation phase).
25	Covers 2 stages: CODE (migration) + VERIFY (adversarial review loop).
26
27	Canonical conversation wrapper:
28	`.codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py`
29	Deterministic engine:
30	`.codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py`
31
32	## Conversation-First Entry
33
34	Bare requests should start with a user-facing action menu, not a wall of CLI
35	flags. Follow the shared contract in
36	`../migrate-to-codex/references/conversational-migration-contract.md`.
37
38	Default menu for underspecified requests:
39
40	1. Assess one agent
41	2. Preview one agent as TOML
42	3. Migrate one agent live
43	4. Batch preflight all agents
44	5. Review one migrated agent for nativeness
45	6. Explain MCP or skill blockers
46
47	Routing rules:
48
49	- If the user already says `preview example-agent-e`, `migrate example-agent-c`,
50	or `review example-agent-e`, route directly.
51	- In Plan mode, use `request_user_input` only for the action choice.
52	- Outside Plan mode, render the same action set as a numbered text menu.
53	- If the action still needs an agent name, ask for it in plain text.
54	- Require explicit confirmation before any live write into `.codex/agents/` or
55	any `--force` overwrite.
56
57	## Advanced CLI
58
59	- Preferred wrappers:
60	- `python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json`
61	- `python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json`
62	- `python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --agent example-agent-a --json`
63	- Power-user engine:
64	- `python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml`
65
66	## Prerequisites
67
68	- Python 3.11+ available
69	- Sibling skill exists: `.codex/skills/migrate-to-codex/` (provides shared functions)
70	- `.codex/agents/` directory will be created by the script if missing
71	- `.codex/config.toml` exists with MCP server definitions
72	- Gold standard reference if present: a previously migrated agent artifact under
73	`.codex/agents/`
74	- Shared conversation contract available at
75	`../migrate-to-codex/references/conversational-migration-contract.md`
76
77	## Format: Markdown vs TOML
78
79	Official Codex custom-agent format is TOML under `.codex/agents/*.toml`.
80
81	Use:
82
83	- `--format toml` for new migrations
84	- `--format md` only for backward-compatible markdown outputs
85
86	Rules:
87
88	- If both `.md` and `.toml` exist for the same agent, treat `.toml` as the
89	runtime-preferred artifact.
90	- Markdown remains useful as documentation and as a bridge for older migration
91	runs, but new custom agents should default to TOML.
92	- Validation must branch by format. A TOML migration is not complete if the
93	workflow still validates only markdown headings.
94
95	## Step 1: Assess Complexity & Resolve Dependencies
96
97	Context: User provides an agent name, a list, `--all`, or a bare request
98	that still needs the menu/front-door routing.
99
100	Before running the backend:
101
102	- bare request -> show the family menu from the shared conversational contract
103	- explicit action + explicit target -> route directly
104	- explicit action + missing target -> ask for the target name
105	- explicit `review <agent>` on

People who liked this also viewed

6 picks

Type

migrate-agents-to-codex

60stars6forks

View on GitHub

How to install migrate-agents-to-codex?

zuharz/ccode-to-codex/migrate-agents-to-codex

$npx -y skills add zuharz/ccode-to-codex --skill migrate-agents-to-codex

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. -->
2	# Migrate Agents to Codex
3
4	## Purpose
5
6	Migrates Claude agent definitions from `.claude/agents/*.md` (YAML frontmatter
7	+ markdown body) to Codex-compatible outputs under `.codex/agents/`.
8
9	Preferred output: standalone TOML custom-agent files.
10	Backward-compatible output only: pure-markdown behavioral specifications.
11
12	The migration strips frontmatter, maps fields to native Codex contracts,
13	preserves runtime hints such as `model`, `effort`, `reasoning_effort`, and
14	`model_reasoning_effort`, normalizes MCP namespaces, and extracts large domain
15	content into companion reference files.
16
17	After migration, a native Codex compliance audit (GPT-5.4 inline
18	sub-agent) validates every migrated file passes as a native Codex sub-agent —
19	not a ported Claude artifact. Mechanical output is never final on write alone:
20	every mechanically generated agent requires a recorded manual nativeness review
21	before it may be treated as native. Findings are auto-addressed and a
22	convergence check confirms no regressions were introduced by the fixes.
23
24	Pipeline position: CODE → VERIFY (runs during implementation phase).
25	Covers 2 stages: CODE (migration) + VERIFY (adversarial review loop).
26
27	Canonical conversation wrapper:
28	`.codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py`
29	Deterministic engine:
30	`.codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py`
31
32	## Conversation-First Entry
33
34	Bare requests should start with a user-facing action menu, not a wall of CLI
35	flags. Follow the shared contract in
36	`../migrate-to-codex/references/conversational-migration-contract.md`.
37
38	Default menu for underspecified requests:
39
40	1. Assess one agent
41	2. Preview one agent as TOML
42	3. Migrate one agent live
43	4. Batch preflight all agents
44	5. Review one migrated agent for nativeness
45	6. Explain MCP or skill blockers
46
47	Routing rules:
48
49	- If the user already says `preview example-agent-e`, `migrate example-agent-c`,
50	or `review example-agent-e`, route directly.
51	- In Plan mode, use `request_user_input` only for the action choice.
52	- Outside Plan mode, render the same action set as a numbered text menu.
53	- If the action still needs an agent name, ask for it in plain text.
54	- Require explicit confirmation before any live write into `.codex/agents/` or
55	any `--force` overwrite.
56
57	## Advanced CLI
58
59	- Preferred wrappers:
60	- `python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json`
61	- `python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json`
62	- `python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --agent example-agent-a --json`
63	- Power-user engine:
64	- `python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml`
65
66	## Prerequisites
67
68	- Python 3.11+ available
69	- Sibling skill exists: `.codex/skills/migrate-to-codex/` (provides shared functions)
70	- `.codex/agents/` directory will be created by the script if missing
71	- `.codex/config.toml` exists with MCP server definitions
72	- Gold standard reference if present: a previously migrated agent artifact under
73	`.codex/agents/`
74	- Shared conversation contract available at
75	`../migrate-to-codex/references/conversational-migration-contract.md`
76
77	## Format: Markdown vs TOML
78
79	Official Codex custom-agent format is TOML under `.codex/agents/*.toml`.
80
81	Use:
82
83	- `--format toml` for new migrations
84	- `--format md` only for backward-compatible markdown outputs
85
86	Rules:
87
88	- If both `.md` and `.toml` exist for the same agent, treat `.toml` as the
89	runtime-preferred artifact.
90	- Markdown remains useful as documentation and as a bridge for older migration
91	runs, but new custom agents should default to TOML.
92	- Validation must branch by format. A TOML migration is not complete if the
93	workflow still validates only markdown headings.
94
95	## Step 1: Assess Complexity & Resolve Dependencies
96
97	Context: User provides an agent name, a list, `--all`, or a bare request
98	that still needs the menu/front-door routing.
99
100	Before running the backend:
101
102	- bare request -> show the family menu from the shared conversational contract
103	- explicit action + explicit target -> route directly
104	- explicit action + missing target -> ask for the target name
105	- explicit `review <agent>` on

People who liked this also viewed

6 picks

Type