OpenAI Codex Rust CLI Agent Best Practices Skill

OpenAI Codex Rust CLI Agent Best Practices

This skill teaches you to write Rust code in the style of the OpenAI Codex codebase - a production CLI/agent system with 50 crates and 787 Rust files.

Key Characteristics

Edition 2024 with strict Clippy configuration
Zero unwrap/expect in non-test code (enforced at workspace level)
Tokio async runtime with proper Send + Sync bounds
thiserror for library errors, anyhow for application code
Flat workspace structure with centralized dependencies

When to Apply

Apply this skill when:

Building CLI tools or agent systems in Rust
Writing async Rust with Tokio
Designing Rust workspace organization
Implementing error handling patterns
Working on production Rust codebases

Quick Reference

Critical Rules (Must Follow)

| Rule | Description | |------|-------------| | err-no-unwrap | Never use unwrap() in non-test code | | err-no-expect | Avoid expect() in library code | | err-thiserror-domain | Use thiserror for domain errors | | err-context-chain | Add context to errors with .context() |

Error Handling

| Rule | Description | |------|-------------| | err-anyhow-application | Use anyhow::Result for entry points | | err-from-derive | Use #[from] for error conversion | | err-transparent | Use #[error(transparent)] for wrapped errors | | err-structured-variants | Include relevant data in error variants | | err-io-result | Use std::io::Result for I/O functions | | err-map-err-conversion | Use map_err for error conversion | | err-doc-errors | Document error conditions |

Organization

| Rule | Description | |------|-------------| | org-workspace-flat | Flat workspace with utils subdirectory | | org-crate-naming | kebab-case directories, project prefix | | org-module-visibility | Use pub(crate) for internal APIs | | org-test-common-crate | Shared test utilities crate | | org-integration-tests-suite | Tests in suite directory | | org-feature-modules | Feature-based module organization | | org-handlers-subdir | Handlers in dedicated subdirectory | | org-errors-file | Errors in dedicated file |

Component Patterns

| Rule | Description | |------|-------------| | mod-derive-order | Consistent derive macro ordering | | mod-async-trait-macro | Use #[async_trait] for async traits | | mod-trait-bounds | Send + Sync + 'static for concurrent traits | | mod-extension-trait-suffix | Ext suffix for extension traits | | mod-builder-pattern | Builder pattern for complex config | | mod-type-alias-complex | Type aliases for complex generics | | mod-impl-block-order | Consistent impl block ordering | | mod-generic-constraints | Where clauses for complex bounds | | mod-newtype-pattern | Newtypes for type safety | | mod-struct-visibility | Private fields with public constructor | | mod-serde-rename | Serde rename for wire format | | mod-jsonschema-derive | JsonSchema for API types |

Naming Conventions

| Rule | Description | |------|-------------| | name-async-no-suffix | No async suffix for async functions | | name-try-prefix-fallible | try prefix for fallible constructors | | name-with-prefix-builder | with_ prefix for builder methods | | name-handler-suffix | Handler suffix for handlers | | name-error-suffix | Error suffix for error types | | name-result-type-alias | Crate-specific Result alias | | name-const-env-var | ENV_VAR suffix for env constants | | name-request-response | Request/Response type pairing | | name-options-suffix | Options suffix for config bundles | | name-info-suffix | Info suffix for read-only data | | name-provider-suffix | Provider suffix for services | | name-client-suffix | Client suffix for API clients | | name-manager-suffix | Manager suffix for lifecycle mgmt | | name-bool-is-prefix | is/has_/should_ for booleans | | name-plural-collections | Plural names for collections |

Style

| Rule | Description | |------|-------------| | style-import-granularity | One item per use statement | | style-deny-stdout | Deny stdout/stderr in libraries | | style-inline-format-args | Inline format arguments | | style-module-docs | Module-level documentation | | style-expect-reason | #[expect] with reason for lints | | style-cfg-test-module | Unit tests in mod tests |

Cross-Crate

| Rule | Description | |------|-------------| | cross-workspace-lints | Workspace-level lint config | | cross-workspace-deps | Centralized dependency versions |

Example: Proper Error Handling

use thiserror::Error;
use anyhow::Context;

// Domain error with thiserror
#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("failed to read config file: {path}")]
    ReadFailed {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error(transparent)]
    Parse(#[from] toml::de::Error),
}

// Library function returns domain error
pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)
        .map_err(|source| ConfigError::ReadFailed {
            path: path.to_owned(),
            source,
        })?;
    toml::from_str(&content).map_err(Into::into)
}

// Application code uses anyhow with context
fn main() -> anyhow::Result<()> {
    let config = load_config(Path::new("config.toml"))
        .context("failed to load configuration")?;
    run(config).await
}

Source

Patterns extracted from OpenAI Codex (codex-rs/ subdirectory) - a production Rust codebase with 50 crates and 787 Rust files.

Agent Skills: OpenAI Codex Rust CLI Agent Best Practices

Install this agent skill to your local

Skill Files