How Claude Code Commands and Codex Skills Differ in Installation and Invocation

Claude Code commands install as raw Markdown files to ~/.claude/commands and invoke with the !command-name prefix, while Codex skills require generation via scripts/sync-codex-skills.py into structured packages at ~/.codex/skills and invoke without the exclamation prefix.

The ai-berkshire repository maintains parallel entry-points for investment research workflows across both Claude Code and Codex. While both platforms execute the same underlying logic defined in skills/*.md, the installation mechanisms, directory structures, and invocation syntax differ significantly to accommodate each platform's native architecture and primitive capabilities.

Installation Architecture and Directory Structure

The primary distinction begins with how each platform consumes the canonical workflow definitions stored in skills/*.md.

Direct Markdown Installation for Claude Code

Claude Code commands install directly from the repository without transformation. The scripts/install-claude-commands.sh script copies the raw Markdown files verbatim to the user's Claude command directory.

The script performs these atomic operations:

1. Creates the destination directory at ${CLAUDE_COMMANDS_DIR:-$HOME/.claude/commands}
2. Copies all skills/*.md files to this location
3. Makes commands immediately available without requiring a restart

This approach works because Claude Code natively interprets Claude-specific primitives such as Task, Agent, and WebSearch directly from the Markdown source.

Generated Package Installation for Codex

Codex skills require a transformation step before installation. The scripts/install-codex-skills.sh orchestrates this two-phase process: first running python3 scripts/sync-codex-skills.py to generate skill packages, then copying each package into $HOME/.codex/skills.

The generation process (specifically lines 64-89 of sync-codex-skills.py) creates a codex-skills/<name>/SKILL.md structure for each workflow. This script injects a Codex adapter note that maps Claude-specific constructs to Codex equivalents—concepts like sub-agents, web-search capabilities, shell commands, and file edit operations.

Unlike Claude Code, Codex requires a restart to load newly installed skills from the ~/.codex/skills directory.

Invocation Patterns and Runtime Behavior

The invocation syntax reflects each platform's command architecture and determines how the workflow executes at runtime.

Running Claude Code Commands

In a Claude Code session, users invoke commands by prefixing the Markdown filename with an exclamation mark:

!investment-research

Claude Code loads the matching file directly from ~/.claude/commands/investment-research.md and executes the workflow using its native interpretation of Claude primitives. The original Markdown is used verbatim without transformation or adapter layers.

Running Codex Skills

Codex users invoke skills without the exclamation prefix:

investment-research

Codex loads the generated SKILL.md from ~/.codex/skills/investment-research/SKILL.md. This file contains both the adapter note—which explains how to translate Claude-specific workflow steps—and the original workflow body. The adapter note ensures that research logic written for Claude's Task and Agent primitives executes correctly using Codex's available capabilities.

Technical Implementation Details

Understanding the generation script and file paths clarifies why this dual-path architecture exists.

The Sync Script and Adapter Logic

The scripts/sync-codex-skills.py generator serves as the compatibility bridge between platforms. When executed, it reads each skills/<name>.md file and produces a corresponding codex-skills/<name>/SKILL.md package. The adapter note injected during generation (lines 64-89) specifically addresses primitives that lack direct equivalents in Codex, ensuring functional parity despite architectural differences.

Source and Target File Paths

• Canonical source: skills/investment-research.md (plain Markdown)
• Claude target: ~/.claude/commands/investment-research.md (verbatim copy)
• Codex target: ~/.codex/skills/investment-research/SKILL.md (generated package with adapter)

This separation prevents naming collisions while allowing both platforms to load their respective formats from distinct locations.

Practical Installation Examples

Install Claude Code commands directly:

./scripts/install-claude-commands.sh

# Commands available immediately

# Usage in Claude: !investment-research

Install Codex skills with generation:

./scripts/install-codex-skills.sh

# Restart Codex to load skills

# Usage in Codex: investment-research

Summary

• Claude Code commands use direct Markdown copies to ~/.claude/commands and require no restart.
• Codex skills require generation via sync-codex-skills.py into package structures at ~/.codex/skills and need a Codex restart.
• Invocation syntax differs by platform: Claude uses !command-name while Codex uses command-name.
• Runtime adaptation occurs only in Codex, where the generator injects adapter notes (lines 64-89) to map Claude primitives to Codex capabilities.
• Source of truth remains the skills/*.md files, with Codex consuming generated derivatives rather than the original Markdown.

Frequently Asked Questions

Why does Codex require a generation step while Claude Code does not?

Codex lacks native support for Claude-specific primitives like Task and Agent constructs. The sync-codex-skills.py script (lines 64-89) generates adapter notes that map these concepts to Codex equivalents such as sub-agents and shell commands. Claude Code reads the Markdown directly because it natively understands its own primitive set.

Can I install both Claude Code commands and Codex skills simultaneously?

Yes. The installation scripts target separate directories (~/.claude/commands versus ~/.codex/skills), preventing conflicts. Run both ./scripts/install-claude-commands.sh and ./scripts/install-codex-skills.sh to enable the workflows on both platforms. Each maintains independent copies of the logic appropriate to its runtime environment.

What happens if I edit a skill file in skills/*.md?

You must reinstall to propagate changes. For Claude Code, rerun ./scripts/install-claude-commands.sh to copy the updated Markdown. For Codex, rerun ./scripts/install-codex-skills.sh to regenerate the codex-skills/*/SKILL.md packages. Codex additionally requires a restart to reload the modified skill definitions.

What is the purpose of the Codex adapter note?

The adapter note, injected by sync-codex-skills.py into each generated SKILL.md, instructs Codex how to interpret workflow steps originally designed for Claude. It maps Claude-only operations to Codex capabilities—translating WebSearch primitives to Codex web-search tools and Agent references to sub-agent invocations—ensuring functional equivalence across platforms.

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