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.

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-provider-runtime, ai-coding-agents-terminal-ui
Execution & safety	ai-coding-agents-execution-sandbox, ai-coding-agents-permissions, ai-coding-agents-settings-policy
State & lifecycle	ai-coding-agents-sessions, ai-coding-agents-tasks, ai-coding-agents-remote-runtime
Extensibility	ai-coding-agents-plugins, ai-coding-agents-tools
Delivery	ai-coding-agents-release-distribution, ai-coding-agents-observability-evals

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

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	Step-by-step from idea to running agent
Which platform should I target?	references/platform-patterns.md	Decision tree: .md vs .toml vs SDK
What single-agent archetypes exist?	references/agent-archetypes.md	Six patterns with frontmatter and tools
When should I use a multi-agent team?	references/multi-agent-coding-patterns.md	Three architectures: coordinator, fork, swarm
How do I manage context for code-heavy work?	references/context-management.md	Token budgets, file selection, progressive disclosure
How do I wrap dev tools for agents?	references/tool-integration.md	Linter, formatter, test runner, type checker patterns
My agent is broken	references/debugging-guide.md	Failure taxonomy and fixes
What do production coding agents look like?	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	File format, validation, and persistence rules
How do swarms, teammates, and worktrees behave?	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	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	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	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
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; Agent(type) tool-scoping syntax gates spawnable subagent types
MCP server setup and integration	../agents-mcp/SKILL.md
Hook guardrails and lifecycle events	../agents-hooks/SKILL.md
Skill packaging and SKILL.md conventions	../agents-skills/SKILL.md
Generic multi-agent orchestration, wave dispatch	../agents-swarm-orchestration/SKILL.md
AGENTS.md (Codex-originated convention) and CLAUDE.md (Claude Code equivalent) configuration	../agents-memory/SKILL.md
Slash-command runtime architecture for coding-agent CLIs	../ai-coding-agents-command-runtime/SKILL.md
Trace, replay, regression evals, and cost accounting	../ai-coding-agents-observability-evals/SKILL.md
Plugin and extension architecture for coding agents	../ai-coding-agents-plugins/SKILL.md
Tool approvals, allow/ask/deny rules, and permission routing	../ai-coding-agents-permissions/SKILL.md
Model-provider abstraction, streaming normalization, and fallback routing	../ai-coding-agents-provider-runtime/SKILL.md
Packaging, update channels, cache migrations, and plugin compatibility	../ai-coding-agents-release-distribution/SKILL.md
Session lifecycle, resume, rewind, and transcript restoration	../ai-coding-agents-sessions/SKILL.md
Local UI plus remote execution architecture	../ai-coding-agents-remote-runtime/SKILL.md
Process isolation, filesystem policy, network controls, and destructive-command boundaries	../ai-coding-agents-execution-sandbox/SKILL.md
Settings precedence, managed policy, and runtime config reload	../ai-coding-agents-settings-policy/SKILL.md
Terminal-first REPL and coding-agent interaction design	../ai-coding-agents-terminal-ui/SKILL.md
Background task runtimes, teammate queues, and task ownership	../ai-coding-agents-tasks/SKILL.md
Tool registry, tool search, and tool execution architecture	../ai-coding-agents-tools/SKILL.md
Testing coding agents (evals, regression)	../qa-agent-testing/SKILL.md
Context loading strategies (generic)	../dev-context-engineering/SKILL.md
Measuring coding agent ROI	../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 or multi-agent patterns.
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/.
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, 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 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.

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 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-wired plus built-in Explore and Task agents. This makes Track A (define an agent on an existing platform) applicable to Copilot CLI in a way it was not a year earlier — treat the earlier "not a coding-agent platform" framing as retired.

Frontmatter shape: description (required), name, target (vscode | github-copilot), tools (omit or ["*"] for all; empty list disables all; MCP tools namespaced as server-name/tool-name), model, disable-model-invocation, user-invocable. Body is Markdown instructions, capped at 30,000 characters. Versioning rides on git commit SHAs rather than a semantic version field.

Where it still falls short of Track B territory: no native multi-agent orchestration (agents can invoke each other via an agent tool alias, but there is no coordinator/fork/team primitive), no formal session-resume or task-graph model, and no sandbox-mode equivalent to Codex's workspace-write / read-only / network-off. Do not port a coordinator-led team or peer-swarm design onto it — the primitives that make those patterns safe (worktree isolation, mailbox protocol, owned-files enforcement) are absent.

When to prefer Copilot CLI: a GitHub-centric repo where a lightweight, PR-aware custom agent is enough — GitHub MCP tools and PR-scoped agent versioning are first-class — and you do not need multi-agent coordination or fine-grained sandbox modes. Prefer Claude Code or Codex when the task needs a coordinator/team pattern, worktree isolation, or a documented permission-mode ladder. Verify current field names and limits against docs.github.com/en/copilot before depending on specifics — this surface is still moving faster than the rest of the platform list. Use scripts/smoke_test.sh to validate that your primary coding-agent setup (Claude Code, Codex, or Agent SDK) is healthy independent of which platform you pick for a given repo.

Single Agent Archetype Index

Archetype	Core Tools	maxTurns	Key Constraint	Template
Code Reviewer	Read, Grep, Glob, Bash	8	Read-only, findings-first output	code-reviewer.md
Test Generator	Read, Write, Edit, Bash, Grep	15	Must run generated tests	test-generator.md
Refactoring Agent	Read, Edit, Bash, Grep, Glob	20	Preserve behavior, run existing tests	refactoring-agent.md
Migration Agent	Read, Write, Edit, Bash, Grep, Glob	25	Pattern-at-a-time, checkpoint between batches	migration-agent.md
Documentation Agent	Read, Write, Grep, Glob	12	Source-anchored, no invented APIs	Universal template
Security Scanner	Read, Grep, Glob, Bash	10	Read-only, severity-ordered output	security-scanner.md

Each archetype is detailed in references/agent-archetypes.md with full frontmatter, system prompt structure, and failure modes.

Multi-Agent Pattern Index