awesome-codex-subagents

What this skill does

```markdown
---
name: awesome-codex-subagents
description: Collection of 136+ specialized Codex subagents in TOML format covering core development, language specialists, infrastructure, quality/security, and more categories.
triggers:
  - set up codex subagents
  - add a codex subagent
  - install codex agent
  - create custom codex subagent
  - configure codex agents directory
  - use specialized ai subagents with codex
  - add backend developer subagent
  - delegate tasks to codex subagents
---

# Awesome Codex Subagents

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A curated collection of 136+ ready-to-use Codex subagents in `.toml` format. Each subagent is a specialized AI assistant scoped to a specific development role — from backend developer to Kubernetes specialist to security auditor. Install them globally or per-project and delegate tasks to them explicitly in your Codex prompts.

---

## What This Project Does

- Provides pre-built `.toml` subagent definitions for Codex
- Each agent has a focused role, tuned model, sandbox permissions, and detailed instructions
- Covers 10 categories: Core Development, Language Specialists, Infrastructure, Quality & Security, AI/ML, Data Engineering, Documentation, Specialized Domains, Workflow, and Research
- Agents are composable — you can use multiple subagents in a single session

---

## Installation

### Prerequisites

- [OpenAI Codex CLI](https://github.com/openai/codex) installed
- A valid Codex session/API access

### Clone the Repository

```bash
git clone https://github.com/VoltAgent/awesome-codex-subagents.git
cd awesome-codex-subagents
```

### Install Global Agents (available in all projects)

```bash
mkdir -p ~/.codex/agents

# Install a single agent
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/

# Install an entire category
cp categories/01-core-development/*.toml ~/.codex/agents/

# Install all agents
cp categories/**/*.toml ~/.codex/agents/
```

### Install Project-Specific Agents (higher precedence)

```bash
mkdir -p .codex/agents

cp categories/04-quality-security/reviewer.toml .codex/agents/
cp categories/04-quality-security/security-auditor.toml .codex/agents/
```

> **Note:** Project-level agents (`.codex/agents/`) override global agents (`~/.codex/agents/`) when names conflict.

---

## Directory Structure

```
awesome-codex-subagents/
├── categories/
│   ├── 01-core-development/
│   │   ├── backend-developer.toml
│   │   ├── frontend-developer.toml
│   │   ├── api-designer.toml
│   │   └── ...
│   ├── 02-language-specialists/
│   │   ├── python-pro.toml
│   │   ├── typescript-pro.toml
│   │   ├── rust-engineer.toml
│   │   └── ...
│   ├── 03-infrastructure/
│   │   ├── devops-engineer.toml
│   │   ├── kubernetes-specialist.toml
│   │   ├── terraform-engineer.toml
│   │   └── ...
│   ├── 04-quality-security/
│   │   ├── code-reviewer.toml
│   │   ├── security-auditor.toml
│   │   ├── qa-expert.toml
│   │   └── ...
│   └── ...
```

---

## Subagent TOML Format

Each subagent is a `.toml` file with this structure:

```toml
name = "backend-developer"
description = "When to invoke: building APIs, server logic, database models, authentication, or any server-side feature"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a senior backend engineer specializing in scalable server-side architecture...

## Core Responsibilities
- Design and implement RESTful and GraphQL APIs
- Write performant database queries and ORM models
- Implement authentication and authorization patterns
- ...
"""
```

### Key Fields

| Field | Description |
|-------|-------------|
| `name` | Unique identifier used to delegate tasks |
| `description` | When Codex should use this agent |
| `model` | Which model powers this agent |
| `model_reasoning_effort` | `low`, `medium`, or `high` |
| `sandbox_mode` | `read-only` or `workspace-write` |
| `[instructions].text` | The full system prompt for the agent |

---

## Model Routing Reference

| Model | Best For | Example Agents |
|-------|----------|----------------|
| `gpt-5.4` | Deep reasoning, architecture, security audits | `security-auditor`, `architect-reviewer` |
| `gpt-5.3-codex-spark` | Fast scanning, synthesis, lighter tasks | `search-specialist`, `docs-researcher` |

---

## Sandbox Mode Reference

| Mode | File Access | Best For |
|------|-------------|----------|
| `read-only` | Can read, cannot write | Reviewers, auditors, analyzers |
| `workspace-write` | Full read/write | Developers, engineers, builders |

---

## Using Subagents in Codex

Codex does **not** auto-spawn custom subagents — you must delegate explicitly in your prompt.

### Basic Delegation

```
Ask the backend-developer subagent to add a POST /api/users endpoint with email validation and bcrypt password hashing.
```

```
Use the typescript-pro subagent to refactor src/utils/date.js to TypeScript with strict types.
```

```
Have the code-reviewer subagent review the changes in src/auth/ for security issues and best practices.
```

### Multi-Agent Workflow

```
1. Use the api-designer subagent to design the schema for a payments API
2. Then have the backend-developer subagent implement it
3. Finally, use the security-auditor subagent to review the implementation
```

### With Specific Files

```
Ask the python-pro subagent to optimize the database queries in app/models/user.py — focus on N+1 query elimination.
```

---

## Creating a Custom Subagent

You can write your own `.toml` agent and drop it in the agents directory:

```toml
# .codex/agents/stripe-integration-expert.toml

name = "stripe-integration-expert"
description = "When working with Stripe payments, webhooks, subscriptions, or billing logic"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

[instructions]
text = """
You are a Stripe integration specialist with deep knowledge of:
- Stripe Checkout and Payment Intents API
- Subscription and billing lifecycle management
- Webhook signature verification and event handling
- SCA/3DS compliance
- Stripe CLI for local webhook testing

## Key Patterns

### Always verify webhook signatures
```python
import stripe
from django.http import HttpResponse

def stripe_webhook(request):
    payload = request.body
    sig_header = request.META.get('HTTP_STRIPE_SIGNATURE')
    
    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, os.environ['STRIPE_WEBHOOK_SECRET']
        )
    except stripe.error.SignatureVerificationError:
        return HttpResponse(status=400)
```

### Use idempotency keys for payment creation
### Handle all relevant webhook event types
### Never log or expose raw card data
"""
```

---

## Category Quick Reference

### Core Development (`01-core-development`)

```bash
cp categories/01-core-development/backend-developer.toml ~/.codex/agents/
cp categories/01-core-development/frontend-developer.toml ~/.codex/agents/
cp categories/01-core-development/api-designer.toml ~/.codex/agents/
cp categories/01-core-development/fullstack-developer.toml ~/.codex/agents/
cp categories/01-core-development/ui-fixer.toml ~/.codex/agents/
```

### Language Specialists (`02-language-specialists`)

```bash
# Install just the languages you use
cp categories/02-language-specialists/python-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/typescript-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/golang-pro.toml ~/.codex/agents/
cp categories/02-language-specialists/rust-engineer.toml ~/.codex/agents/
cp categories/02-language-specialists/nextjs-developer.toml ~/.codex/agents/
```

### Infrastructure (`03-infrastructure`)

```bash
cp categories/03-infrastructure/devops-engineer.toml ~/.codex/agents/
cp categories/03-infrastructure/terraform-engineer.toml ~/.codex/agents/
cp categories/03-infrastructure/kubernetes-specialist.toml ~/.codex/agents/
cp categorie