overview

Cross-technology entry point for agentic AI: choosing the implementation layer (harness vs Agent SDK vs raw model API vs managed agents), workflow-vs-agent architecture and the five workflow patterns,

Files8

View on GitHub

SKILL.md

GitHub

Agentic AI — Domain Overview

The routing skill for cross-cutting "how should we build this with AI agents?" questions. It owns four decisions that come before any product-specific work: which layer to build on, whether the thing is a workflow or an agent, how to orchestrate multiple agents, and how to budget context. It also carries the cross-vendor harness comparison and enterprise rollout guidance.

Always answer the layer and workflow-vs-agent questions first, then hand off to the specific sibling skill. Never re-derive a sibling's depth here — this skill is the map, not the territory. Comparison and selection are what this skill owns; the moment a question becomes "how do I configure/run this tool", route it to that tool's own skill.

Routing map

The question is about… Go to
Configuring/deploying the Claude Code harness (settings, permissions, hooks, subagents, plugins, headless CI) claude-code
Operating OpenAI Codex — CLI, config.toml, approvals/sandbox, codex exec, Codex cloud codex
Operating GitHub Copilot — IDE/agent mode, the coding agent, Copilot CLI, enterprise policies github-copilot
Operating Cursor — modes, rules, permissions, hooks, cloud/background agents, cursor-agent cursor
Operating pi (pi.dev) — TUI/print/RPC/SDK modes, settings, extensions, provider switching pi
Building a custom agent in TypeScript/Python on the Claude Agent SDK claude-agent-sdk
Building an agent on the OpenAI Agents SDK (Python openai-agents / TS @openai/agents) openai-agents-sdk
Building an agent on Google ADK (LlmAgent, workflow agents, tools, sessions) google-adk
Raw Messages API — model IDs, tool use, streaming, caching, batches, structured outputs claude-api
MCP itself — spec, transports, primitives, OAuth, writing or consuming servers mcp
Writing a SKILL.md, progressive disclosure, skill authoring agent-skills
Which frontier model / capability tier across Anthropic, OpenAI, Google model-selection
Prompt injection, tool poisoning, OWASP GenAI risks, AI governance frameworks ai-security
Isolation and egress control mechanics for running agents safely sandboxing
Training or tuning a model (LoRA/QLoRA/GRPO, hosted tuning APIs) fine-tuning
Building training data (formats, quality, synthetic data) training-datasets
Measuring models, agents, or skills — graders, LLM-as-judge, regression suites evals
SIEM/EDR/WAF/SAST platform tooling the marketplace's security plugin
Kubernetes/container runtime depth under an agent platform the marketplace's containers plugin

Decision 1 — pick the layer

Always name the layer explicitly before designing anything. Four layers exist; teams routinely pick one heavier than their problem needs.

Situation Layer Why
Interactive development, one-off terminal tasks, a human in the loop CLI harness (Claude Code, Codex CLI, Gemini CLI) Batteries-included agent loop, filesystem config, zero code to write
You want an agent but not to implement the tool loop Agent SDK (Claude Agent SDK, OpenAI Agents SDK) The harness's loop, tools, context management, and guardrails embedded in your own process
You need full manual control of every model call and tool execution Raw model API (Anthropic Client SDK / Messages API, OpenAI Responses API) Bespoke orchestration that doesn't fit an agent-loop's assumptions
Long-running or async agents, and you don't want to run sandbox/session infra Managed Agents (Anthropic-hosted REST API) Anthropic runs the agent and the sandbox

Directives:

  • Always start at the harness when a human is driving. Reach for the SDK only when the work must run headless, at scale, or inside a larger system. Every step down the ladder is code you now own forever.
  • The Claude Agent SDK is "Claude Code as a library" — same loop, tools, and context management, in Python and TypeScript only. From any other language, drive the CLI as a subprocess with -p --output-format json rather than reimplementing the loop.
  • Never assume harness config is lost when you move to the SDK: skills, commands, memory, and plugins still load from .claude/ and ~/.claude/.
  • If you are building a product on the Agent SDK, check the branding and auth constraints before you name it — "Claude Code" branding is not permitted for third parties, and claude.ai login cannot be offered inside a third-party SDK product without prior approval.

Read references/layer-selection.md when the user is weighing SDK-vs-API, comparing Anthropic's four-way split against OpenAI's Responses-API-vs-Agents-SDK split, or asking what the five agent primitives are.

Decision 2 — workflow or agent

The line is control flow, not sophistication:

  • Workflow — LLMs and tools orchestrated through predefined code paths.
  • Agent — the LLM dynamically directs its own process and tool usage.

Directives:

  • Always find the simplest thing that passes evaluation — often a single well-tooled LLM call, frequently a workflow, sometimes not an agentic system at all. Every autonomous turn adds latency, tokens, and the chance an early mistake propagates.
  • Use an agent only for open-ended problems with an unpredictable number of steps where you cannot hardcode the path but can still verify progress. No verification signal means no agent.
  • Never deploy an agent outside a sandboxed environment with guardrails — autonomy implies trusting its decisions, so bound the blast radius mechanically. Hand the mechanics to sandboxing.
  • Build the augmented LLM first: one model plus curated retrieval, tools, and memory, with clear documented interfaces. MCP is one way to wire in third-party tools.

The five workflow patterns, in ascending autonomy:

Pattern Use when
Prompt chaining The task decomposes into fixed sequential subtasks; accuracy matters more than latency; add programmatic gates between steps
Routing Inputs fall into distinct categories handled better separately, and classification is reliable
Parallelization Independent subtasks (sectioning) or repeated attempts aggregated for confidence (voting)
Orchestrator-workers Subtasks cannot be predicted in advance — a central LLM decomposes, delegates, then synthesizes
Evaluator-optimizer Clear evaluation criteria exist and iterative critique measurably improves the output

Orchestrator-workers is the first genuinely agentic pattern: it differs from parallelization precisely because the subtasks are not predefined.

Read references/workflow-patterns.md for each pattern's mechanism and worked examples, the three agent design principles, and the tool-definition (agent-computer interface) rules.

Decision 3 — orchestration, only after one agent demonstrably fails

Start with one agent whenever you can. Add specialists only when they demonstrably improve capability isolation, policy isolation, prompt clarity, or trace legibility — premature splitting adds prompts and traces without improving the workflow.

Three failure modes justify separate context windows, and they are the diagnostic to look for before splitting:

  1. Agentic laziness — the agent stops before finishing a complex multi-part task after partial progress.
  2. Self-preferential bias — it favors its own prior findings when independent verification is what's needed.
  3. Goal drift — fidelity to the original objective decays across many turns.

Named orchestration patterns worth reaching for by name:

  • Classify-and-Act / Routing — classify, then dispatch to a specialized agent.
  • Fan-Out-and-Synthesize — parallel agents, structured merge at a synchronization barrier.
  • Adversarial Verification — a separate rubric-driven verifier judges the primary agent's output.
  • Tournament — N differing approaches, pairwise judged.
  • Loop Until Done — repeat until explicit stop conditions, never a fixed iteration count.
  • Generate-and-Filter — many candidates, then quality-filter and dedupe.
  • Handoffs (decentralized) — control transfers wholly to a specialist for that branch.
  • Manager pattern (centralized) — the orchestrator keeps control and calls specialists as bounded tools, synthesizing the final answer itself.

Constraints that make multi-agent work in practice: set explicit per-subagent token budgets; keep resource-intensive commands out of parallel branches so branches don't contend; isolate overlapping work in separate git worktrees; give verification agents a skeptic persona so they don't rubber-stamp; keep each specialist's job narrow and its handoff description short and concrete.

Never apply this to routine day-to-day work — multi-agent orchestration consumes far more tokens than a single agent and only pays off on complex, high-value tasks.

Read references/orchestration.md for the dynamic-workflows model, the full pattern catalog with mechanisms, and the handoff-vs-manager code shapes.

Decision 4 — engineer the context

Context engineering is curating and maintaining the optimal set of tokens across the whole inference budget: system prompt, tool definitions, tool results, memory, retrieved data, and history — not just the opening instructions.

  • Treat context as a finite resource with diminishing returns. Context rot is real: attention quality degrades as tokens compete, because self-attention creates n² pairwise relationships. A bigger window does not make extra context free.
  • Write system prompts in the "Goldilocks zone" — sectioned with XML tags or Markdown headers, minimal at first, extended only in response to observed failure modes. Never pre-emptively encode imagined edge cases.
  • Curate tools: self-contained, minimal functional overlap, unambiguous parameters. Bloated tool sets degrade tool-selection accuracy.
  • Prefer a few diverse canonical few-shot examples over exhaustive edge-case enumeration.
  • Default to just-in-time retrieval: hold lightweight identifiers (paths, URLs, queries) and load the data through tools at runtime. Pre-loading everything is the single most common context-budget mistake.
  • Use compaction for long-horizon tasks — summarize history near the limit, preserving architectural decisions while dropping redundant tool output. The tension is recall vs precision.
  • Use structured note-taking (e.g. a NOTES.md) for state that must survive dozens of tool calls.
  • Use subagents for focused exploration in a clean window, returning ~1,000–2,000 token condensed summaries to the coordinator.

Read references/context-engineering.md for the full principles plus how a shipping harness implements them mechanically (skill description-vs-body loading, session persistence, the post-compaction skill re-attachment budgets).

Harness landscape

This section is the comparison grid only. Operational depth for each harness lives in its own skill — claude-code, codex, github-copilot, cursor, pi — so answer "which one / how do they differ" here and route "how do I configure or run it" there. Gemini CLI has no dedicated skill; its coverage below and in references/harness-landscape.md is its only home.

Three major CLI coding-agent harnesses are compared below as of 2026-08-05. They have converged on the same shape — a memory/instruction file, a layered config file, MCP for external tools, a sandbox plus approval policy, a headless mode, and admin-managed enterprise overrides — so evaluate on that grid rather than on feature lists.

Axis Claude Code OpenAI Codex CLI Google Gemini CLI
Instruction file CLAUDE.md + auto memory AGENTS.md / AGENTS.override.md GEMINI.md (filenames configurable, incl. AGENTS.md)
Config settings.json (user / project / local / managed) config.toml (user / project / system, plus profiles) settings.json (system / workspace / user / defaults)
MCP config claude mcp add, .mcp.json, scoped local/project/user [mcp_servers.<name>] in config.toml, codex mcp add mcpServers in settings.json
Safety model Permission modes + hooks sandbox_mode × approval_policy GEMINI_SANDBOX mechanism + approval mode
Headless claude -p (JSON output) codex exec --json gemini -p
Enterprise Managed settings, managed MCP requirements.toml (enforced) + managed_config.toml (defaults) System settings.json + policy engine + wrapper script

Directives:

  • Standardize on one harness per org, then encode team rules in the instruction file and enforce them through the managed/system config layer — not through onboarding docs. Only Codex's requirements.toml and Gemini's system settings are enforced; managed defaults are merely starting values a user can change.
  • Always keep required team guidance in the checked-in instruction file, not in per-user "memories" — memories are a recall layer, not the source of truth for rules that must always apply.
  • Never run any harness with sandboxing and approvals both disabled (--yolo, danger-full-access, YOLO mode) outside an already-hardened, disposable environment. Running arbitrary model-generated shell commands requires sandboxing, resource limits, command filtering, and logging before production use.
  • Nested instruction files beat root ones in both Codex and Gemini (later in the concatenation wins), so scope overrides by directory rather than growing one large file.

Read references/harness-landscape.md for per-harness install, auth, config keys, sandbox mechanisms, headless flags, and enterprise controls — at comparison depth. Beyond the grid, go to the owning skill: claude-code, codex, github-copilot, cursor, or pi.

Enterprise adoption

  • Be deliberately strategic, not broad-and-shallow. Sustained returns come from deployments that compound; assume no deployment compounds automatically.
  • Target revenue-generating capability, not only cost reduction, and encode institutional knowledge into systems so value accumulates.
  • Keep human-in-the-loop oversight at critical decision points. Compress high-friction information workflows while deliberately preserving human judgment where decisions are made — do not automate the decision away.
  • Map upskilling to specific organizational processes rather than generic AI-literacy training.
  • Phase the rollout (a structured six-month rollout is the vendor-suggested shape for a platform like Claude Cowork) instead of an enterprise-wide big-bang.

Read references/enterprise-adoption.md before advising on rollout governance; it also records which vendor material was not verifiable, so you don't state unverified specifics as fact.

Anti-patterns

  • Building an agent when a workflow (or one augmented LLM call) passes eval — the default failure of new agent projects.
  • Splitting into multiple agents before a single agent has demonstrably failed on laziness, bias, or goal drift.
  • Pre-loading every possibly-relevant document instead of just-in-time retrieval.
  • Growing tool sets without curation, then blaming the model for wrong tool selection.
  • Treating tool definitions as an afterthought — they deserve the same rigor and testing as prompts.
  • Relying on a subagent's report being trustworthy: reports can carry untrusted text from files, web pages, and command output. Restrict what a subagent can reach; see ai-security for injection handling.
  • Fixed iteration counts where explicit stop conditions belong.

Reference files

  • references/layer-selection.md — harness vs Agent SDK vs Client SDK vs Managed Agents; OpenAI's Responses-API-vs-Agents-SDK split; the five agent primitives; SDK licensing/branding constraints. Read for "what should we build on?"
  • references/workflow-patterns.md — the five workflow patterns in detail, agent implementation principles, tool/agent-computer-interface design rules. Read when designing the control flow.
  • references/orchestration.md — dynamic workflows, the six Claude Code orchestration patterns, OpenAI handoffs vs manager pattern, multi-agent context budgets. Read when one agent is not enough.
  • references/context-engineering.md — context rot, system-prompt strategy, JIT retrieval, compaction, note-taking, subagent summaries, and how Claude Code enforces skill-content token budgets. Read for token-budget and long-horizon-task questions.
  • references/harness-landscape.md — Claude Code, Codex CLI, and Gemini CLI: install, auth, config format, memory files, MCP wiring, sandbox/approval models, headless mode, enterprise controls. Read for harness selection or migration, not for operating a harness — claude-code, codex, github-copilot, cursor, and pi own that depth.
  • references/enterprise-adoption.md — enterprise rollout pillars, production lessons, and explicitly flagged coverage gaps. Read for org-level adoption advice.

Diagnostic scripts

  • scripts/01-harness-inventory.sh — read-only inventory of which agent harnesses are installed and which instruction/config/MCP files exist for the current project and user. Run it before advising on harness standardization or migration.

Sources

Fetched: 2026-08-05

Related in development

update-docs-vercel-next-js

This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what d...

by vercel
137,316

docstring-pytorch-pytorch

Write docstrings for PyTorch functions and methods following PyTorch conventions. Use when writing or updating docstring...

by pytorch
96,875

at-dispatch-v2

Convert PyTorch AT_DISPATCH macros to AT_DISPATCH_V2 format in ATen C++ code. Use when porting AT_DISPATCH_ALL_TYPES_AND...

dispatch
by pytorch
95,362