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

> Explore the Codex CLI skills system's features. This plugin framework offers automatic tool invocation, caching, and UI controls for a seamless developer experience.

- Repository: [OpenAI/codex](https://github.com/openai/codex)
- Tags: architecture
- Published: 2026-03-06

---

**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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/core/src/skills/model.rs) (lines 32-35) governs whether skills execute automatically. The `allow_implicit_invocation()` method implements the logic:

```rust
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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/core/src/skills/model.rs) (lines 68-75) aggregates execution results including:

- Successfully loaded skills
- Load errors (malformed [`SKILLS.md`](https://github.com/openai/codex/blob/main/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:

```rust
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:

```rust
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:

```rust
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:

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

```

## Summary

- **Rich metadata system**: Skills are defined via `SkillMetadata` in [`SKILLS.md`](https://github.com/openai/codex/blob/main/SKILLS.md) with support for descriptions, icons, and scope classification in [`codex-rs/core/src/skills/model.rs`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/core/src/skills/manager.rs) merges settings from system-wide, user-specific, and repository-local [`config.toml`](https://github.com/openai/codex/blob/main/config.toml) files. Each skill's metadata is stored in a [`SKILLS.md`](https://github.com/openai/codex/blob/main/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`](https://github.com/openai/codex/blob/main/codex-rs/tui/src/slash_command.rs)), which sends `AppEvent::SetSkillEnabled` events to update `Config` settings. Alternatively, edit the [`config.toml`](https://github.com/openai/codex/blob/main/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`.