Ai Coding Agents

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 ai-coding-agents-* 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 traps, patterns and anti-patterns for one subsystem. Build order and subsystem owners: references/runtime-build-spine.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.

Quick Reference

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

Default Workflow

The goal is a bounded agent whose scope, tools, and verification you can state in one sentence before it runs. Classify the task first — what code it touches, what tools it needs, what it emits — and decide single agent (one bounded task) or team (interdependent tasks, parallel reviews, complex investigation). Pick the closest archetype or multi-agent pattern, then the platform: Claude Code .md for repo-level agents, Codex .toml for Codex workflows, Agent SDK for programmatic integration. Start from the matching template in assets/templates/.

Scope tools to the minimum: read-only agents get Read, Grep, Glob; edit agents add Edit, Write, Bash. "Read-only" is enforced by the permission layer or the sandbox, never by the prompt: an agent granted Bash can write files, so a reviewer or scanner that needs Bash runs under deny rules for writing commands or inside a read-only sandbox. Design the context strategy alongside it — which files the agent needs, how it discovers them, what token budget it has — and decide how the agent checks its own work.

Rule: rules/repo/agent-defs.md loads this invariant when Claude edits an agent definition in this library.

Before copying a platform template, build a small capability record from the target runtime: available tools, writable roots, approval path, context-start behavior, background/cancellation support, and installed model. Treat configured, advertised, and successfully exercised capabilities as separate states; template parity does not prove runtime parity. A template counts as proven on a runtime only after a canary task has exercised its capability record there, including at least one action the record says must be denied.

Two verification checks before deploying:

• Smoke test on 3+ representative tasks. For teams, the verifier must be a separate agent, not the one that made the change.
• Extension robustness for edit, refactor, and migration agents: run at least one evolving-spec sequence with 3+ checkpoints, each started in a fresh conversation/context, carrying forward the same agent-created workspace and retaining all prior regression tests.

Then iterate on observed behavior: tighten scope, improve prompts.

Before the first session on a machine, run scripts/smoke_test.sh (--help for details) against the project root: CLI installed, tool registry present, and sandbox enabled by parsed settings. The CLI check is an install check; it probes model access only when run with an API key and SMOKE_TEST_MODEL. A [FAIL] Sandbox engaged line means Bash in that project runs unsandboxed, so read-only archetypes are not enforced there.

Choose the model per task, not per agent fleet: route routine edits to a cheaper workhorse model and reserve the frontier model for the hard minority (planning, cross-module debugging, review of risky diffs). Savings figures for this split are practitioner self-reports, not measurements; before choosing the split, read the provider's current pricing page (and the runtime's model-config docs for which aliases resolve to which models), since tier names and per-token prices change between releases.

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)

Validated-by-use patterns from OpenAI's internal Codex report: optional two-stage Ask to Code flow, environment-as-prompt, prompt-as-GitHub-issue, task queue as lightweight backlog, and Best-of-N as a generation primitive. Detail, sources and anti-patterns: references/openai-internal-practice-codex.md. The task-sizing heuristic lives in ../ai-coding-agents-state/SKILL.md.

Platform Decision Tree

See references/platform-patterns.md for side-by-side comparison and porting guide.

Goose (OSS, MCP and ACP, recipe YAML, custom distros) and GitHub Copilot CLI (.agent.md custom agents, no native multi-agent or sandbox-mode ladder) are covered in references/additional-platforms-goose-and-copilot-cli.md. Prefer Claude Code or Codex when the task needs a coordinator or team pattern, worktree isolation, or a documented permission-mode ladder.

Single Agent Archetype Index

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

Multi-Agent Pattern Index

Pattern selection, coordinator, fork, peer-swarm, background-agent and ACP-delegation detail, and the shared multi-agent principles (never delegate understanding, freeze interfaces, exclusive owned files, separate verifiers, fresh workers at phase boundaries, files for state, escalation, notification-driven planning, nesting depth as a ceiling) are in references/multi-agent-coding-patterns.md.

Context Management Essentials

Code is large and interdependent, so split the window into instructions, code and output budgets, read by progressive disclosure (directory structure, key files, then targeted sections), and separate read-only exploration from editing. Split into subagents with clear file ownership when a task spans more than 5-10 unrelated files. Detail: references/context-management.md; skill-subagent isolation: ../agents-subagents/SKILL.md.

Templates and Entry Points

• Single agent: claude-code-agent.md, code-reviewer.md, test-generator.md, refactoring-agent.md, migration-agent.md, security-scanner.md
• Multi-agent: coordinator-coding-team.md, swarm-investigation.md, parallel-review-team.md
• Cross-platform: codex-agent.toml, sdk-agent-py.py, sdk-agent-ts.ts
• Checklists: agent-design-checklist.md, multi-agent-checklist.md, production-readiness.md

Navigation

References

• references/creation-workflow.md — End-to-end creation guide
• references/platform-patterns.md — Claude Code vs Codex vs Agent SDK
• references/agent-archetypes.md — Six single-agent coding patterns
• references/multi-agent-coding-patterns.md — Five multi-agent patterns
• references/context-management.md — Token budgets and file strategies
• references/tool-integration.md — Dev tool wrapping patterns
• references/debugging-guide.md — Failure taxonomy and fixes
• references/production-patterns.md — Patterns from shipped coding-agent runtimes
• references/claude-code-prompt-recipes.md — Named prompt recipes for setup, planning, execution, review, and debug/recovery
• references/openai-internal-practice-codex.md — OpenAI internal Codex practice patterns
• references/additional-platforms-goose-and-copilot-cli.md — Goose and GitHub Copilot CLI as target platforms
• references/runtime-build-spine.md — Runtime build order with subsystem owners, invariants, false shortcuts

Assets

• assets/templates/ — Agent definition and team templates
• assets/checklists/ — Design, dispatch, and deployment checklists

Data

• data/sources.json — Primary documentation and research references

Platform and Source Notes

• Agent definition field names and allowed values come from the runtime's current docs; read them in ../agents-subagents/references/runtime-surfaces.md and verify against current runtime behavior before depending on one.
• Platform-specific capabilities (Codex sandbox modes and current model names, SDK hook patterns, GitHub Copilot CLI's custom-agent and plugin surface) should be verified against current platform documentation — the Copilot CLI surface in particular moves faster than the rest of this platform list.
• Star counts, model names, and other numeric/product-name claims cited for Goose, career-ops, and similar community projects drift continuously; treat any figure here as a snapshot, not a live value.

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.