Codex Learning Skill

Learn to configure and optimize OpenAI Codex CLI for maximum productivity.

Actions

Action	Description	Example
`learn`	Start learning guide	`$codex-learning learn`
`setup`	Configuration walkthrough	`$codex-learning setup`
`tips`	Best practices and tips	`$codex-learning tips`

What is Codex CLI?

Codex CLI is OpenAI's command-line coding agent that:

Reads and writes files in your project
Executes shell commands
Uses tools via MCP (Model Context Protocol)
Follows instructions from AGENTS.md files
Invokes skills for specialized tasks

Quick Start

1. Installation

npm install -g @openai/codex

2. Configuration

# Create config directory
mkdir -p ~/.codex

# Create config.toml
cat > ~/.codex/config.toml << 'CONFIG'
model = "o4-mini"
approval_mode = "suggest"

[history]
persistence = "save_all"
save_to = "$HOME/.codex/history"

[sandbox]
network_access = true
CONFIG

3. Project Setup

Create AGENTS.md at your project root:

# Project Agent Instructions

## Project Overview
Brief description of this project.

## Tech Stack
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- Backend: bkend.ai BaaS
- Level: Dynamic

## Conventions
- Use TypeScript strict mode
- Follow ESLint + Prettier rules
- Commit messages: conventional commits format

## File Structure
[Describe your project structure]

## Important Notes
[Project-specific instructions for the AI]

AGENTS.md Guide

Location Hierarchy

project/
├── AGENTS.md                # Root (applies to entire project)
├── src/
│   ├── AGENTS.md           # Applies to src/ and subdirectories
│   ├── components/
│   │   └── AGENTS.md       # Applies to components/
│   └── lib/
│       └── AGENTS.md       # Applies to lib/

Child AGENTS.md files inherit from parent and can add/override instructions.

Best Practices for AGENTS.md

Be specific: "Use TypeScript strict mode" not "write good code"
Include conventions: Naming rules, file structure, patterns
List tech stack: Framework versions, key dependencies
Define boundaries: What the AI should and should not do
Keep it updated: Review and update as project evolves

MCP Server Configuration

What is MCP?

Model Context Protocol allows Codex to connect to external tools and data sources.

Configure MCP Servers

// ~/.codex/mcp.json
{
  "servers": {
    "bkit-codex": {
      "command": "npx",
      "args": ["bkit-codex-mcp"],
      "description": "bkit development pipeline tools"
    }
  }
}

Project-level MCP

// .codex/mcp.json (in project root)
{
  "servers": {
    "project-tools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"]
    }
  }
}

Skills System

What are Skills?

Skills are reusable instruction sets that Codex loads when triggered by keywords in your prompt.

Skill Structure

.agents/skills/
├── my-skill/
│   ├── SKILL.md              # Instructions (YAML frontmatter + body)
│   └── agents/
│       └── openai.yaml       # Codex-specific config

SKILL.md Format

---
name: my-skill
description: |
  Brief description of what this skill does.
  Triggers: keyword1, keyword2, keyword3
  Do NOT use for: things this skill should not handle.
---

# Skill Body

Instructions for the AI when this skill is activated.

openai.yaml Format

interface:
  brand_color: "#3B82F6"
policy:
  allow_implicit_invocation: true

Approval Modes

Mode	Description	Best For
`suggest`	Shows changes, asks before applying	Learning, careful work
`auto-edit`	Auto-applies file edits, asks for commands	Experienced users
`full-auto`	Auto-applies everything	Trusted workflows

Best Practices

Effective Prompts

Be specific about what you want
Reference file paths explicitly
Mention the framework/language
Ask for one thing at a time for complex tasks

Project Organization

Keep AGENTS.md up to date
Use .codex/ for project-specific config
Store skills in .agents/skills/
Use MCP for tool integration

Performance Tips

Use o4-mini for fast tasks, o3 for complex reasoning
Break large tasks into smaller steps
Use skills to provide context instead of repeating instructions
Keep AGENTS.md concise (under 2000 words)

Codex CLI Reference

See references/codex-guide.md for complete command reference and advanced configuration.

codex-learning