🧱 Fundamentals

A coding agent is an LLM that runs an autonomous loop: reads code, plans, edits files, runs commands, and reviews its own results — unlike autocomplete, which only suggests the next line.

Without this mental model, you use Claude Code/Codex as if they were Copilot and miss 90% of the value. The agent handles tasks end to end, not just snippets of code.

ReAct loop (reasoning + action), tool use, permissions, persistent session context, event hooks.

Markdown file in the project root that the agent reads automatically at the start of every session. Claude Code looks for CLAUDE.md; Codex looks for AGENTS.md. Same function, different name.

It's the "project manual" the agent always keeps in mind. Well written, it saves you from repeating context every session. Poorly written, it becomes noise that gets ignored.

Global hierarchy (~/.claude/CLAUDE.md) vs. project, direct instructions, code conventions, build/test commands, links to internal docs.

Hidden folder in the project where everything specific to the agent lives: settings, skills, sub-agents, hooks. Claude uses .claude/; Codex uses .codex/ for config and .agents/ for skills.

This is where you customize the agent’s behavior per project. Without understanding this folder, you’re stuck with defaults — and defaults are never ideal for your workflow.

Global vs. project (tilde-dot vs. dot), semantic folders (skills/, agents/, commands/), settings.json and config.toml, partial gitignore (commit skills, ignore credentials).

A skill is a “packaged capability”: a file SKILL.md with YAML frontmatter (name, description) + a Markdown body explaining how to perform a task, activated automatically when the trigger appears in context.

Skills are the modern way to teach the agent behavior without bloating CLAUDE.md/AGENTS.md. Both runtimes implement the Agent Skills standard (agentskills.io) — with only a few differences.

YAML frontmatter, activation by description (semantic match), directories scripts//references//assets/, slash invocation (/skill) vs. dollar invocation ($skill).

A sub-agent is a "specialized persona" that the main agent can delegate tasks to. Claude Code discovers and invokes sub-agents automatically; Codex requires you to call them by name.

This is the biggest shock between the two. People who migrate forget and get frustrated, thinking Codex "doesn't have sub-agents." It does — it just doesn't call them on its own.

Markdown format (Claude) vs. TOML (Codex), description as an auto-selection trigger, context isolation, parallel agent dispatch, token cost.

Model Context Protocol is an open standard for connecting LLMs to external tools (Slack, Gmail, databases, etc.). Claude Code and Codex consume MCP servers in the same way.

MCP is the part of the stack that does NOT change between runtimes. Configure an MCP server and it works for both. Only the way you declare the dependency changes.

stdio vs. HTTP server, declaration in .mcp.json, tool exposed as mcp__server__tool, permissions/allowlist per server.

Each agent has distinct strengths: Claude tends to be more thorough with long refactors and deep debugging; Codex is usually faster on small tasks and follows hard prompts to the letter.

Knowing which tool to use for each task saves hours. It’s not “which is better” — it’s “which is better for this right now.”

Reasoning style (planner-heavy vs doer-heavy), tolerance for ambiguity, behavior when editing large files, cost per token.

A pattern observed by people who use both: when an agent gets stuck in a loop, repeats the same mistake, or loses track, passing the context to the other one often resolves it in seconds.

It's the #1 reason to have both installed. No need to wait for support or struggle — open the second agent, paste the summary, and move on.

Session handoff (cf. T6.1), context dump in Markdown, "fresh eyes effect," near-zero switching cost when the project is well documented.

Providers go down. Limits are reached. If your productivity depends 100% on Anthropic OR OpenAI, any instability takes you offline. Having both ensures continuity.

If you bill by the hour or have a deadline, the cost of waiting is greater than the cost of both subscriptions. Do the math.

Status pages (status.anthropic.com, status.openai.com), rate limits by time window, manual fallback, “tool-agnostic” as a principle.

Everything that is NOT agent configuration (source code, docs, scripts, READMEs, wikis) is read the same way by both. You don't duplicate any of it.

This is the point that unlocks coexistence: 95% of the project is shared. Only the 5% of configuration needs translation — and polyskill handles that translation for skills.

Source code, documentation, ADRs, shell scripts, sample data — everything is shared. Only skills, sub-agents, and settings are duplicated.

An attitude of not marrying yourself to one tool. The coding agent ecosystem changes quickly — Gemini CLI, Cursor, Copilot, JetBrains, and whatever comes next. Your skill should survive a tool switch.

People who get stuck on one runtime suffer every time something better comes along. People who write portable content can migrate in hours. polyskill is the technical expression of that mindset.

Open spec (agentskills.io), canonical format vs. runtime format, pluggable adapters, drift policy, “rewrite once, deploy many.”

Yes, that’s two plans to pay for. But how much is an hour of your time worth when you’re blocked by a stuck agent? How much is it worth to learn the dominant ecosystem when the tide turns?

To justify the choice to yourself (and your team/client) with numbers, not vibes. There are scenarios where one is enough—and scenarios where two is the minimum.

Usage-based plan vs. subscription, opportunity cost, knowledge depreciation, value of redundancy in critical workflows.