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

> Discover the distinct installation and invocation methods for Claude Code commands versus Codex skills. Learn how to integrate and run them easily.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: deep-dive
- Published: 2026-07-26

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash
!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:

```bash
investment-research

```

Codex loads the generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash
./scripts/install-claude-commands.sh

# Commands available immediately

# Usage in Claude: !investment-research

```

Install Codex skills with generation:

```bash
./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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-claude-commands.sh) and [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./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`](https://github.com/xbtlin/ai-berkshire/blob/main/./scripts/install-claude-commands.sh) to copy the updated Markdown. For Codex, rerun [`./scripts/install-codex-skills.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/./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`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py) into each generated [`SKILL.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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.