---
name: ai-coding-agents
description: "Creates coding agents on Claude Code, Codex, and Agent SDK. Use when defining review, test, refactor, or team agents — not building a runtime."
compatibility: Portable core. Works on Claude Code and Codex.
version: "1.2"
last_validated: 2026-08-21
---

# AI Coding Agents — Creation Hub

Use this skill to go from a coding agent idea to a working agent definition, whether a single-purpose agent or a coordinated multi-agent coding team.

This skill owns the coding-domain-specific creation workflow, templates, and patterns. For agent architecture decisions and build-vs-not gates, start with [`../ai-agents/SKILL.md`](../ai-agents/SKILL.md).

## Two Different Tracks

This skill (and its siblings prefixed `ai-coding-agents-*`) split into two tracks with different audiences. Pick the right one before going deeper.

**Track A — Create an agent on an existing platform (this skill).**
Use this umbrella when the platform exists (Claude Code, Codex, or Agent SDK) and you need to define an agent on top of it: frontmatter, tools, archetype, multi-agent coordination. This is the common case.

**Track B — Build a coding-agent runtime from scratch (the 14 sibling skills).**
Use the dedicated curriculum when you are building the runtime itself — the thing that loads agents, sandboxes execution, routes tool calls, manages sessions. Each skill captures known traps, patterns, and anti-patterns for one subsystem:

| Concern | Skills |
|---------|--------|
| Runtime architecture | [`ai-coding-agents-command-runtime`](../ai-coding-agents-command-runtime/SKILL.md), [`ai-coding-agents-provider-runtime`](../ai-coding-agents-provider-runtime/SKILL.md), [`ai-coding-agents-terminal-ui`](../ai-coding-agents-terminal-ui/SKILL.md) |
| Execution & safety | [`ai-coding-agents-execution-sandbox`](../ai-coding-agents-execution-sandbox/SKILL.md), [`ai-coding-agents-permissions`](../ai-coding-agents-permissions/SKILL.md), [`ai-coding-agents-settings-policy`](../ai-coding-agents-settings-policy/SKILL.md) |
| State & lifecycle | [`ai-coding-agents-sessions`](../ai-coding-agents-sessions/SKILL.md), [`ai-coding-agents-tasks`](../ai-coding-agents-tasks/SKILL.md), [`ai-coding-agents-remote-runtime`](../ai-coding-agents-remote-runtime/SKILL.md) |
| Extensibility | [`ai-coding-agents-plugins`](../ai-coding-agents-plugins/SKILL.md), [`ai-coding-agents-tools`](../ai-coding-agents-tools/SKILL.md) |
| Delivery | [`ai-coding-agents-release-distribution`](../ai-coding-agents-release-distribution/SKILL.md), [`ai-coding-agents-observability-evals`](../ai-coding-agents-observability-evals/SKILL.md) |

If the request is "how do I add a slash command to my runtime?" or "how should I design approval prompts?", route to Track B. If it's "how do I define a code-review agent on Claude Code?", stay here.

## ASCII Flow

```text
user need
  |
  v
classify: define agent on existing platform OR build runtime subsystem
  |
  +--> existing platform
  |      -> choose platform: Claude Code | Codex | Agent SDK
  |      -> choose archetype or team pattern
  |      -> scope tools + context + verification
  |      -> smoke test on representative coding tasks
  |
  +--> runtime subsystem
         -> route to ai-coding-agents-* sibling skill
         -> design subsystem contract + invariants + failure modes
         -> validate with host/runtime-specific tests
```

## Quick Reference

| Question | Read | Outcome |
|----------|------|---------|
| How do I create a coding agent end-to-end? | [`references/creation-workflow.md`](references/creation-workflow.md) | Step-by-step from idea to running agent |
| Which platform should I target? | [`references/platform-patterns.md`](references/platform-patterns.md) | Decision tree: `.md` vs `.toml` vs SDK |
| What single-agent archetypes exist? | [`references/agent-archetypes.md`](references/agent-archetypes.md) | Six patterns with frontmatter and tools |
| When should I use a multi-agent team? | [`references/multi-agent-coding-patterns.md`](references/multi-agent-coding-patterns.md) | Three architectures: coordinator, fork, swarm |
| How do I manage context for code-heavy work? | [`references/context-management.md`](references/context-management.md) | Token budgets, file selection, progressive disclosure |
| How do I wrap dev tools for agents? | [`references/tool-integration.md`](references/tool-integration.md) | Linter, formatter, test runner, type checker patterns |
| My agent is broken | [`references/debugging-guide.md`](references/debugging-guide.md) | Failure taxonomy and fixes |
| What do production coding agents look like? | [`references/production-patterns.md`](references/production-patterns.md) | Real patterns from Claude Code source |
| How does Claude Code define and validate agents? | [`references/claude-code-agent-runtime-patterns.md`](references/claude-code-agent-runtime-patterns.md) | File format, validation, and persistence rules |
| How do swarms, teammates, and worktrees behave? | [`references/claude-code-swarm-and-worktree-patterns.md`](references/claude-code-swarm-and-worktree-patterns.md) | Team files, inherited flags, worktree lifecycle |
| How are skills and built-in plugins loaded? | [`references/claude-code-skill-and-plugin-loading.md`](references/claude-code-skill-and-plugin-loading.md) | Frontmatter loading, plugin-backed skills, prompt budgets |
| Which prompt recipes steer a Claude Code session to a specific outcome? | [`references/claude-code-prompt-recipes.md`](references/claude-code-prompt-recipes.md) | 35 named recipes covering setup, planning, execution, review, debug/recovery, and session economics |
| Should I route a coding task to a cheap or premium model? | [`references/multi-model-routing-economics.md`](references/multi-model-routing-economics.md) | 85/15 routing pattern, cost/context tradeoffs — re-verify live numbers before costing |

## When To Use

- Create a new coding agent from scratch on any supported platform
- Choose the right archetype for a coding task (review, test generation, refactoring, migration, docs, security)
- Design a multi-agent team for complex coding tasks (parallel reviews, bug investigation, migration fleets)
- Design context loading strategy for agents working with large codebases
- Wrap existing dev tools (linters, formatters, test runners, type checkers) for agent use
- Debug a coding agent producing poor results, hallucinated files, or scope creep
- Port a coding agent between platforms (Claude Code ↔ Codex ↔ Agent SDK)

## Use Other Skills

| Need | Use Instead |
|------|-------------|
| Agent architecture decisions, build-vs-not | [`../ai-agents/SKILL.md`](../ai-agents/SKILL.md) |
| Subagent frontmatter, delegation contracts | `agents-subagents` — current fields include `name`, `description`, `model` (alias `fable` valid), `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `initialPrompt`, `background`, `isolation` (`worktree` only value), `color`; `permissionMode` field noted but `auto` value and plugin-subagent restrictions apply — see [`../ai-coding-agents-permissions/SKILL.md`](../ai-coding-agents-permissions/SKILL.md); `Agent(type)` tool-scoping syntax gates spawnable subagent types |
| MCP server setup and integration | [`../agents-mcp/SKILL.md`](../agents-mcp/SKILL.md) |
| Hook guardrails and lifecycle events | [`../agents-hooks/SKILL.md`](../agents-hooks/SKILL.md) |
| Skill packaging and SKILL.md conventions | [`../agents-skills/SKILL.md`](../agents-skills/SKILL.md) |
| Generic multi-agent orchestration, wave dispatch | [`../agents-swarm-orchestration/SKILL.md`](../agents-swarm-orchestration/SKILL.md) |
| AGENTS.md (Codex-originated convention) and CLAUDE.md (Claude Code equivalent) configuration | [`../agents-memory/SKILL.md`](../agents-memory/SKILL.md) |
| Slash-command runtime architecture for coding-agent CLIs | [`../ai-coding-agents-command-runtime/SKILL.md`](../ai-coding-agents-command-runtime/SKILL.md) |
| Trace, replay, regression evals, and cost accounting | [`../ai-coding-agents-observability-evals/SKILL.md`](../ai-coding-agents-observability-evals/SKILL.md) |
| Plugin and extension architecture for coding agents | [`../ai-coding-agents-plugins/SKILL.md`](../ai-coding-agents-plugins/SKILL.md) |
| Tool approvals, allow/ask/deny rules, and permission routing | [`../ai-coding-agents-permissions/SKILL.md`](../ai-coding-agents-permissions/SKILL.md) |
| Model-provider abstraction, streaming normalization, and fallback routing | [`../ai-coding-agents-provider-runtime/SKILL.md`](../ai-coding-agents-provider-runtime/SKILL.md) |
| Packaging, update channels, cache migrations, and plugin compatibility | [`../ai-coding-agents-release-distribution/SKILL.md`](../ai-coding-agents-release-distribution/SKILL.md) |
| Session lifecycle, resume, rewind, and transcript restoration | [`../ai-coding-agents-sessions/SKILL.md`](../ai-coding-agents-sessions/SKILL.md) |
| Local UI plus remote execution architecture | [`../ai-coding-agents-remote-runtime/SKILL.md`](../ai-coding-agents-remote-runtime/SKILL.md) |
| Process isolation, filesystem policy, network controls, and destructive-command boundaries | [`../ai-coding-agents-execution-sandbox/SKILL.md`](../ai-coding-agents-execution-sandbox/SKILL.md) |
| Settings precedence, managed policy, and runtime config reload | [`../ai-coding-agents-settings-policy/SKILL.md`](../ai-coding-agents-settings-policy/SKILL.md) |
| Terminal-first REPL and coding-agent interaction design | [`../ai-coding-agents-terminal-ui/SKILL.md`](../ai-coding-agents-terminal-ui/SKILL.md) |
| Background task runtimes, teammate queues, and task ownership | [`../ai-coding-agents-tasks/SKILL.md`](../ai-coding-agents-tasks/SKILL.md) |
| Tool registry, tool search, and tool execution architecture | [`../ai-coding-agents-tools/SKILL.md`](../ai-coding-agents-tools/SKILL.md) |
| Testing coding agents (evals, regression) | [`../qa-agent-testing/SKILL.md`](../qa-agent-testing/SKILL.md) |
| Context loading strategies (generic) | [`../dev-context-engineering/SKILL.md`](../dev-context-engineering/SKILL.md) |
| Measuring coding agent ROI | [`../dev-ai-coding-metrics/SKILL.md`](../dev-ai-coding-metrics/SKILL.md) |
| Claude API and Agent SDK reference | claude-api skill |

## Default Workflow

1. **Classify the task**: What code does the agent touch? What tools does it need? What is the output?
2. **Single agent or team?** One bounded task → single agent. Multiple interdependent tasks, parallel reviews, or complex investigation → multi-agent team.
3. **Pick the archetype** closest to your need from the [archetypes](#single-agent-archetype-index) or [multi-agent patterns](#multi-agent-pattern-index).
4. **Choose the platform**: Claude Code `.md` for repo-level agents, Codex `.toml` for Codex workflows, Agent SDK for programmatic integration.
5. **Start from the matching template** in [`assets/templates/`](assets/templates/).
6. **Scope tools** to the minimum needed. Read-only agents get Read, Grep, Glob. Edit agents add Edit, Write, Bash.
7. **Design the context strategy**: What files does the agent need? How does it discover them? What is the token budget?
8. **Add verification**: How does the agent check its own work? For teams: assign a separate verifier.
9. **Smoke test**: Run on 3+ representative tasks before deploying.
10. **Test extension robustness**: For edit, refactor, and migration agents, run at least one evolving-spec sequence with 3+ checkpoints. Start each checkpoint in a fresh conversation/context, carry forward the same agent-created workspace, and retain all prior regression tests.
11. **Iterate**: Observe real behavior, tighten scope, improve prompts.

## Known Traps

- giving a coding agent repo-wide edit authority before the owned files and verification surface are clear
- asking the same agent to implement, review, and approve its own high-risk changes
- inheriting parent context blindly across phases instead of re-briefing from current repo truth
- building a multi-agent coding team before the task graph, file ownership, and merge plan exist
- assuming Claude Code, Codex, and SDK workers expose equivalent tools, hooks, and approval semantics
- treating one-shot green tests, a plan-first prompt, or an anti-slop prompt as evidence that edit-capable agents remain extensible over repeated changes

## Common Anti-Patterns

- "full-stack fixer" agents with no bounded artifact, path, or runtime scope
- tool wrappers that hide destructive commands behind vague natural-language instructions
- edit-capable workers launched in parallel on the same branch with no ownership contract
- context strategies that preload too much code instead of progressive disclosure and file selection
- smoke tests skipped because the prompt "looks right"

## OpenAI Internal Practice (Codex, 2026-05)

Source: [*How OpenAI uses Codex*](https://cdn.openai.com/pdf/6a2631dc-783e-479b-b1a4-af0cfbd38630/how-openai-uses-codex.pdf), May 2026 — internal-usage report across Security, Product, Frontend, API, Infrastructure, and Performance Engineering teams. These patterns are validated by daily use inside OpenAI; cite this source rather than restating as your own observations.

### Two-stage Ask → Code flow for non-trivial changes

- **Pattern:** for any change above the trivial single-file fix, run Ask Mode first to produce an implementation plan. Then switch to Code Mode and feed the plan as input to follow-up prompts.
- **Why:** keeps the agent grounded; the plan becomes a self-correction surface — if the plan is wrong, the human catches it before generation rather than after.
- **Anti-pattern:** going straight to Code Mode for a multi-file change. The agent will improvise structure that the human then has to reverse-engineer at review time.
- **Recipe:** *"Plan the implementation for X. Do not write code yet."* → review plan → *"Execute the plan above, file by file."*

### Environment-as-prompt (compoundable)

- **Pattern:** treat the agent's runtime environment — startup script, env vars, internet access — as part of the persistent prompt. Iterate on env config every time a build error appears and ask whether the env should have prevented it.
- **Why:** env improvements compound. A startup script that installs the right toolchain once removes a category of errors from every future task in the repo.
- **Anti-pattern:** treating env failures as one-off prompt fixes. The agent re-discovers the same gap on every new task.
- **Recipe:** maintain a single `setup.sh` (or equivalent) that the agent runs at session start; add to it when a class of build error recurs.

### Prompt-as-GitHub-Issue

- **Pattern:** structure prompts the way you would write a PR description or issue — file paths, component names, diffs, doc snippets, and "implement this the same way it's done in [module X]" anchors.
- **Why:** the model already responds well to PR/issue-shaped text from training distribution; this is free signal that doesn't require new tooling.
- **Anti-pattern:** chat-shaped prompts ("can you change the auth flow?") that omit the repo coordinates the agent needs to act precisely.

### Task queue as lightweight backlog

- **Pattern:** fire off tangential ideas, partial work, or incidental fixes as separate Codex tasks rather than holding them in human working memory. The queue *is* the backlog; no obligation to produce a full PR per task.
- **Why:** captures drive-by fixes without forcing context switches; staging area mirrors the engineer's working set.
- **Where this lives in this skill:** see [`../ai-coding-agents-tasks/SKILL.md`](../ai-coding-agents-tasks/SKILL.md) for the task-runtime detail and the sizing heuristic (~1 hour of human work / a few hundred LOC).

### Best-of-N as a generation primitive

- **Pattern:** generate N parallel solutions for a single task and either pick the best or combine parts of multiple outputs.
- **Why:** for ambiguous or open-ended tasks, the cheapest quality-improving move is variance, not better prompting.
- **Anti-pattern:** running Best-of-N on tasks with one obviously correct shape (mechanical refactors, type fixes). Wasted compute; pick prompt engineering instead.
- **Vendor scope:** Codex-specific feature surface. The equivalent on other runtimes is parallel subagent dispatch — see [`../agents-swarm-orchestration/SKILL.md`](../agents-swarm-orchestration/SKILL.md).

## Platform Decision Tree

| Scenario | Platform | Why |
|----------|----------|-----|
| Repo-team agent, auto-delegated by description | Claude Code `.md` | Description-driven routing, shared via `.claude/agents/` |
| Codex thread workers | Codex `.toml` | Explicit spawning, sandbox-mode scoped |
| Codex as tool inside an editor or AI orchestrator | `codex mcp-server` (stdio) | Codex acts as an MCP server; editor drives it over MCP wire protocol |
| Non-interactive code review in CI | `codex review` subcommand | Headless, no terminal UI; structured output for pipelines |
| Programmatic, CI, or API integration | Agent SDK | Full control, custom tools, hook callbacks |
| Quick prototype | Claude Code `.md` | Fastest path to working agent |
| Multi-agent coordinator team | Claude Code `.md` | Native coordinator mode, fork, and team support |
| Custom orchestration logic | Agent SDK | Programmatic control over spawning, routing, results |
| Local-first OSS coding agent, editor-integrated via ACP (Zed, JetBrains, IntelliJ) | Goose (Rust) + recipe YAML | ACP server mode; 70+ MCP extensions; custom-distros; Apache-2.0 |
| Enterprise white-label coding agent with pinned providers and extensions | Goose Custom Distribution | Distro manifest baked into the binary; supply-chain gates (`deny.toml`); AAIF/LF governance |
| GitHub-centric repo, lightweight PR-aware agent, no multi-agent need | GitHub Copilot CLI custom agent (`.agent.md`) | Pre-wired GitHub MCP server, PR-scoped agent versioning; see Copilot CLI section below for its ceiling |

See [`references/platform-patterns.md`](references/platform-patterns.md) for side-by-side comparison and porting guide.

### Goose as a fourth platform (2026)

Goose (github.com/aaif-goose/goose, formerly github.com/block/goose) is a 50k+-star Rust-based OSS coding agent donated by Block to the Agentic AI Foundation (AAIF) under the Linux Foundation. It is a meaningfully different platform from Claude Code / Codex / Agent SDK:

- **Protocols:** first-class MCP *and* ACP. Goose runs as an ACP server (`goose acp`) so editors drive it over stdio; Goose can also delegate to external ACP agents (Claude Code, Codex) as providers.
- **Unit of work:** a **recipe** — YAML with `version / title / description / instructions / extensions / activities / prompt / parameters`. Recipes are portable, statically validated, and declare their extension dependencies inline.
- **Distribution:** supports custom distros (white-label, pinned providers/extensions, branded binaries) as a first-class shipping class.
- **Project hints:** uses `.goosehints` alongside `AGENTS.md` — one more member of the narrative-hint family (see `../agents-memory/SKILL.md`).

Treat it as the target when a coding agent must be OSS, editor-embedded, locally-operated, or enterprise-forkable. Detailed patterns live in the subsystem skills under "Cross-Platform Patterns (Goose)" sections — most relevantly in `ai-coding-agents-provider-runtime` (toolshim, agent-as-provider), `ai-coding-agents-remote-runtime` (ACP stdio, daemon+OpenAPI), `ai-coding-agents-tasks` (recipes as typed blueprints), and `ai-coding-agents-release-distribution` (custom distros).

### GitHub Copilot CLI — a fifth, lighter-weight platform (revised 2026)

GitHub Copilot CLI outgrew its "explains shell commands" origin during 2026. It now defines **custom agents** as Markdown files with YAML frontmatter (`.agent.md`, resolvable at repo or org scope), supports a **plugin system** (`/plugin install owner/repo`) that bundles MCP servers, agents, skills, and hooks, and ships with the GitHub MCP server pre-w