Codex CLI Skills System: Architecture, Features, and Implementation Guide

The Codex CLI skills system is a discoverable, configurable plugin framework that enables automatic and manual invocation of external tools through rich metadata, per-directory caching, and integrated UI controls.

The Codex CLI skills system provides a flexible extension mechanism that allows users to augment OpenAI's Codex with reusable, discoverable skills. Implemented primarily in Rust across the openai/codex repository, this system supports both implicit automatic invocation and explicit manual execution through a layered configuration architecture.

Rich Skill Metadata and Declaration

Every skill is defined by the SkillMetadata struct located in codex-rs/core/src/skills/model.rs (lines 10-21). This structure captures:

• Human-readable identifiers including full and short descriptions
• Interface hints such as display names, icons, brand colors, and default prompts
• Scope classification via SkillScope variants (System, User, or Repo) determining where the skill resides
• Invocation policy controlling automatic execution behavior

Skill authors define these properties in a SKILLS.md file within the skill's directory, enabling skill creation without modifying Rust source code.

Implicit Invocation Policy Control

The SkillPolicy struct in codex-rs/core/src/skills/model.rs (lines 32-35) governs whether skills execute automatically. The allow_implicit_invocation() method implements the logic:

fn allow_implicit_invocation(&self) -> bool {
    self.policy
        .as_ref()
        .and_then(|p| p.allow_implicit_invocation)
        .unwrap_or(true)
}

When this returns true, the core engine may invoke the skill automatically when its trigger pattern matches user intent, without requiring explicit /skill commands.

Per-Directory Loading and Caching

The SkillsManager in codex-rs/core/src/skills/manager.rs resolves active skills through the skills_for_cwd method (lines 76-85). This implementation:

• Merges system, user, and repository skill roots based on the active configuration stack
• Caches results in RwLock<HashMap<PathBuf, SkillLoadOutcome>> for fast subsequent lookups via cached_outcome_for_cwd
• Supports forced reload via force_reload when installing new skills

Automatic System Skill Installation

During initialization, SkillsManager::new (lines 36-43) calls install_system_skills(&codex_home). This ensures built-in system skills are present on fresh machines, guaranteeing core functionality regardless of user configuration state.

Tool Dependency Validation

Skills declare external requirements through SkillToolDependency defined in codex-rs/core/src/skills/model.rs (lines 52-60). Before execution, the CLI validates:

• External binary availability
• Network URL accessibility
• Required transport mechanisms

This prevents runtime failures by ensuring dependencies exist prior to invocation.

UI Integration and Interaction Patterns

The skills system surfaces multiple interaction surfaces in the terminal UI:

Slash Command Interface

The /skills command defined in codex-rs/tui/src/slash_command.rs (lines 24-26) opens the skill management interface.

Toggle View

SkillsToggleView in codex-rs/tui/src/bottom_pane/skills_toggle_view.rs displays discoverable skills with checkboxes for runtime enable/disable control.

Skill Detail Popups

Clicking a skill opens a detailed popup (implemented in skill_popup.rs) showing descriptions, icons, and SkillToolDependency information.

Mention Autocomplete

When users type @skill-name, the system creates UserInput::Skill events handled in codex-rs/tui/src/chatwidget/skills.rs, supporting both explicit invocation and policy-driven implicit execution.

Configuration Layer Integration

Skills integrate with the standard Codex config.toml hierarchy through SkillsConfig. Users can enable or disable skills per configuration layer, and SkillsManager computes the final active set by merging system, user, and repository configurations according to precedence rules.

Error Handling and Load Outcomes

SkillLoadOutcome in codex-rs/core/src/skills/model.rs (lines 68-75) aggregates execution results including:

• Successfully loaded skills
• Load errors (malformed SKILLS.md, missing dependencies)
• Disabled skill paths

The UI surfaces these outcomes in the skill list view, allowing users to remediate configuration issues immediately.

Working with Skills: Code Examples

Listing Available Skills

Request a fresh skill list from the TUI event loop:

app.submit_op(Op::ListSkills {
    extra_skill_roots: vec![],
});

This sends a ListSkills operation to the core; SkillsManager::skills_for_cwd returns a SkillLoadOutcome rendered in SkillsToggleView.

Enabling or Disabling Skills

Toggle skills at runtime through configuration updates:

app_event_tx.send(AppEvent::SetSkillEnabled {
    name: "git-branch".to_string(),
    enabled: true,
});

This triggers Config::set_skill_enabled and updates the cached SkillLoadOutcome for the current directory.

Explicit Skill Invocation

Invoke skills directly with command arguments:

app.submit_op(Op::UserTurn {
    input: UserInput::Skill {
        path: "git-branch".into(),
        args: vec!["create".into(), "feature-x".into()],
    },
});

The core resolves the skill, validates SkillToolDependency requirements, and executes the associated tool (typically a script in the skill's scripts/ folder).

Implicit Invocation Flow

For automatic execution when policy permits:

if skill.allow_implicit_invocation() && skill.matches(&request) {
    execute_skill(skill, request);
}

Summary

• Rich metadata system: Skills are defined via SkillMetadata in SKILLS.md with support for descriptions, icons, and scope classification in codex-rs/core/src/skills/model.rs.
• Flexible invocation: Supports both explicit /skill commands and automatic implicit invocation controlled by SkillPolicy settings.
• Hierarchical configuration: Integrates with Codex's config.toml layers (system, user, repo) for granular enable/disable control via SkillsConfig.
• Performance optimization: SkillsManager caches per-directory skill lists in RwLock<HashMap<PathBuf, SkillLoadOutcome>> to avoid repeated disk operations.
• Dependency safety: SkillToolDependency validation ensures required binaries and URLs exist before execution in codex-rs/core/src/skills/model.rs.
• Auto-installation: System skills install automatically via install_system_skills during SkillsManager initialization (lines 36-43).
• Integrated UI: Slash commands, toggle views, and mention autocomplete provide multiple interaction patterns through codex-rs/tui components.
• Robust error handling: SkillLoadOutcome captures and surfaces load errors and disabled states in the TUI.

Frequently Asked Questions

What is the Codex CLI skills system?

The Codex CLI skills system is a plugin framework in the openai/codex repository that allows users to extend Codex functionality through reusable, discoverable skills—small programs invoked automatically or manually based on metadata-defined triggers and policies stored in SKILLS.md files.

How does implicit invocation work in the Codex CLI?

Implicit invocation is controlled by the allow_implicit_invocation field in SkillPolicy (defined in codex-rs/core/src/skills/model.rs at lines 32-35). When this boolean is true and the skill's trigger pattern matches user input, SkillsManager automatically executes the skill without requiring the user to type a /skill command, as implemented in the core matching logic.

Where are skill configurations stored in Codex CLI?

Skill configurations reside in the standard Codex configuration hierarchy. The SkillsManager in codex-rs/core/src/skills/manager.rs merges settings from system-wide, user-specific, and repository-local config.toml files. Each skill's metadata is stored in a SKILLS.md file within the skill's directory, parsed by the loader to create SkillMetadata objects.

How do I enable or disable specific skills in the Codex CLI?

You can toggle skills through the SkillsToggleView interface (accessed via the /skills slash command in codex-rs/tui/src/slash_command.rs), which sends AppEvent::SetSkillEnabled events to update Config settings. Alternatively, edit the config.toml directly to set per-skill enablement flags, which SkillsManager reads when computing the active skill set for the current working directory via skills_for_cwd.

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