Migrating from Claude Code to Codex CLI Workflow for PM Skills: Complete Guide

You can migrate from Claude Code to Codex CLI by swapping command prefixes and replacing slash commands with natural language descriptions, while keeping all plugin manifests and skill files identical.

The PM Skills Marketplace is a modular collection of 9 plugins bundling 68 skills and 42 commands for product management workflows. This guide covers the minimal syntax changes required to move your workflow from Claude Code to the Codex CLI while maintaining full compatibility with the existing repository structure in phuryn/pm-skills.

Understanding the PM Skills Architecture

Before migrating, you need to understand how the repository structure supports both tools simultaneously.

Plugin Structure

The repository organizes functionality into nine plugin directories under the repo root, such as pm-toolkit/, pm-product-discovery/, and pm-go-to-market/. Each plugin contains a .claude-plugin/plugin.json manifest that defines the plugin's name, version, description, and author metadata.

Marketplace Manifest

The .claude-plugin/marketplace.json file serves as the central registry that both Claude Code and Codex CLI consume. This JSON file lists all nine plugins and provides descriptions used by both clients to surface available functionality. According to the source code, this file is located at the repository root and remains unchanged during migration.

Skill and Command Definitions

Skills are reusable knowledge units stored in pm-<category>/skills/<skill>/SKILL.md. Each skill directory must match the name field in its front-matter exactly, enforced by the validate_plugins.py script.

Commands are slash-triggered workflows stored in pm-<category>/commands/<command>.md. Their front-matter includes description and argument-hint fields. While Claude Code exposes these as slash commands (e.g., /discover), Codex CLI interprets natural language descriptions to invoke the same underlying skills.

Step-by-Step Migration Process

Migration requires only changing CLI command prefixes; no code or file modifications are necessary.

1. Update Marketplace Registration

Replace the Claude Code prefix with Codex CLI when adding the marketplace:

# Claude Code syntax

claude plugin marketplace add phuryn/pm-skills

# Codex CLI syntax

codex plugin marketplace add phuryn/pm-skills

2. Install Plugins with New Syntax

Install individual plugins using the updated command structure:

# Claude Code

claude plugin install pm-toolkit@pm-skills

# Codex CLI

codex plugin add pm-toolkit@pm-skills

The pm-toolkit@pm-skills reference remains identical across both platforms, pointing to the same plugin.json manifest in the pm-toolkit/.claude-plugin/ directory.

3. Replace Slash Commands with Natural Language

Convert your workflow invocations from slash commands to descriptive prompts.

Claude Code approach:

/discover AI-powered meeting summarizer for remote teams

Codex CLI approach:

Run product discovery on AI-powered meeting summarizer for remote teams: brainstorm ideas, identify assumptions, prioritize assumptions, and design experiments.

Codex CLI will internally invoke the same four discovery skills defined in pm-product-discovery/skills/ that the /discover command chains in Claude Code.

4. Validate Your Installation

Run the validation scripts to ensure manifests and skill directories remain consistent:

python3 validate_plugins.py
python3 -m unittest discover -s tests

The validate_plugins.py script checks that all plugin.json manifests, skill directories, and command front-matter obey the design rules, verifying version alignment across the repository as documented in CHANGELOG.md.

Key Differences Between Claude Code and Codex CLI

Command Syntax Changes

The primary migration friction points are the command prefixes and installation verbs:

• Marketplace management: claude plugin marketplace add becomes codex plugin marketplace add
• Plugin installation: claude plugin install becomes codex plugin add
• Plugin removal: Use codex plugin remove instead of claude plugin uninstall

Workflow Invocation Methods

Claude Code exposes explicit slash commands defined in markdown files under pm-<category>/commands/. The front-matter in these files (e.g., pm-product-discovery/commands/discover.md) supplies the text shown when users type /discover.

Codex CLI does not expose slash commands. Instead, users describe the desired workflow in plain language, and Codex invokes the underlying skills via natural-language prompts. Both tools ultimately execute the same skill definitions located in the skills/ subdirectories.

Validation and Testing

After migration, verify the integrity of your PM Skills installation using the built-in validation suite.

The validate_plugins.py script performs the following checks:

• Confirms all 9 plugin manifests contain valid JSON with required fields (name, version, description)
• Validates that skill folder names match the name field in their respective SKILL.md front-matter
• Ensures version numbers align across all plugin.json files and CHANGELOG.md

Unit tests in the tests/ directory verify count consistency (ensuring all 68 skills and 42 commands are properly registered) and cross-reference the marketplace manifest against actual plugin directories.

Summary

• Zero file changes are required when migrating from Claude Code to Codex CLI for the PM Skills repository.
• Swap claude command prefixes for codex and change install to add when managing plugins.
• Replace slash commands (e.g., /discover) with natural language descriptions of the workflow you want to execute.
• The .claude-plugin/marketplace.json and individual plugin.json manifests work identically in both tools.
• Run validate_plugins.py and the tests/ suite after migration to confirm all 9 plugins and 68 skills remain properly configured.

Frequently Asked Questions

Do I need to modify plugin.json files when migrating to Codex CLI?

No. The plugin.json manifests located in each plugin's .claude-plugin/ directory are neutral JSON files that both Claude Code and Codex CLI consume identically. The pm-toolkit/.claude-plugin/plugin.json structure and all other plugin manifests remain unchanged during migration.

How do I run discovery workflows in Codex CLI without slash commands?

Describe the workflow in plain language rather than using the /discover slash command. For example, state "Run product discovery on [topic]" and list the specific steps you want Codex to execute. Codex will invoke the same four discovery skills stored in pm-product-discovery/skills/ that the /discover command chains in Claude Code.

What validation should I run after migration?

Execute python3 validate_plugins.py to check manifest consistency and python3 -m unittest discover -s tests to run the unit test suite. These scripts verify that all 9 plugins maintain proper version alignment and that the 68 skills and 42 commands remain properly registered according to the repository's design rules.

Are all 9 plugins compatible with Codex CLI?

Yes. All plugins in the marketplace—including pm-toolkit, pm-product-discovery, and pm-go-to-market—are fully compatible with Codex CLI because the tool reads the same .claude-plugin/marketplace.json file and skill definitions that Claude Code uses. The only difference is the client-side command syntax used to install and invoke them.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}