Here is a confession that might sound odd in a guide about setting up Claude Code: the goal is not to marry Claude Code. The goal is to build a setup so portable that if something better ships next month — OpenAI's Codex, Cursor, Windsurf, whatever wins the week — you could pack up everything you have built and move in an afternoon. Your instructions, your custom tools, your reusable workflows: all of it should come with you.
That sounds like a strange thing to optimize for. Most "best setup" posts try to lock you deeper into one tool. But the AI coding world is moving too fast for that bet to be safe, and — happily — a small set of open standards now make portability the default instead of a fantasy. If you are a working engineer, this is how you stop re-plumbing your environment every time you switch editors. And if you are a vibe coder — someone who builds mostly by describing what you want in plain English and steering the AI, a style Andrej Karpathy named in early 2025 — this is how you get a professional-grade setup without months of fiddling.
The short version: keep your AI's instructions, tools, and skills in plain, open formats you own — not buried in one vendor's settings. Three standards make this work: MCP for tools, AGENTS.md for instructions, and Agent Skills for reusable know-how. Learn those, and the question "which coding agent should I use?" stops being scary.
Three standards do the heavy lifting here, and we will spend most of our time on them: MCP AGENTS.md Agent Skills. Let's build up to a setup you would actually be happy to leave.
Think of your setup as interchangeable bricks, not a sculpture glued to one base. Photo by Xavi Cabrera on Unsplash.
Why portability is the whole game now
In the last 18 months, more than a dozen serious AI coding agents have shipped: Claude Code, OpenAI Codex, Cursor, Windsurf, Zed's agent, Aider, Cline, Continue, Gemini CLI, and more. Each one claims to be the fastest or the smartest. Some genuinely leapfrog the others — for a few weeks, until the next release.
Here is the trap. If you pour weeks into one tool — memorizing its config files, hand-tuning its rules, wiring up its integrations — you have quietly built a switching cost. The day a clearly better tool arrives, you do the math on re-learning everything and you stay put, not because your tool is best, but because leaving hurts. That is the real lock-in. It is not a contract; it is your own sunk effort.
The fix is to treat the agent as a replaceable part and invest in the layer underneath it. The engineer Geoffrey Huntley has made this point sharply: the agents themselves are becoming commodities, and the durable advantage is the standards layer you build around them. Put your effort there, and any agent becomes a front-end you can swap.
An analogy: remember when every phone had its own charger, and switching brands meant a drawer full of dead cables? USB-C fixed that by agreeing on one shape. You buy a charger once; it works with the next phone, and the one after. The standards below are USB-C for your AI setup. Learn them once, and your tools become things you plug into — not things you are wired into.
The three open standards that set you free
You do not need to memorize specs. You need to understand what each standard is for, because once you see the shape of the problem each one solves, the portability falls out naturally. They split cleanly: one is for tools, one is for instructions, one is for skills.
MCP — one way to plug in tools
The Model Context Protocol (MCP) is an open standard, created and open-sourced by Anthropic in November 2024, for connecting an AI to outside tools and data — your database, your GitHub, your Notion, your company's internal services.
If you have used a code editor, you have already benefited from this idea. Editors once needed custom code to support each programming language, until the Language Server Protocol let any editor talk to any language through one shared interface. MCP does the same trick for AI and tools. Instead of every AI app writing a custom integration for every service — an N-times-M explosion — you write one MCP server for a service, and every MCP-compatible host can use it. The math collapses from N times M down to N plus M.
Mechanically, a host (Claude Code, Cursor, ChatGPT, and others) runs a client that talks to your server over one of two transports: stdio for a local tool running as a subprocess, or streamable HTTP for a remote service. The server exposes tools, read-only resources, and prompt templates; the host stays in charge of what the model is actually allowed to touch. Crucially, the configuration looks almost identical across tools — a small block naming each server:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
},
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
}
}
}Move from Claude Code to Cursor or Codex and you copy that block over, rename one key if needed, and your tools come with you. One safety note worth tattooing on your brain: an MCP server can run code and reach real systems, so only install servers you trust, keep secrets in environment variables like the ${GITHUB_TOKEN} above rather than hard-coding them, and review what each tool is permitted to do.
MCP is the wiring: many tools, one shared protocol. Photo by Alina Grubnyak on Unsplash.
AGENTS.md — a README for your AI
Every project has unspoken rules: how to install it, how to run the tests, which folders are off-limits, what "good code" means here. A human teammate learns these over weeks. An AI agent starts fresh every session and will happily reinvent your conventions unless you write them down.
That is what AGENTS.md is — a plain Markdown file at the root of your repo that tells any coding agent how to work on your project. No special syntax, no required fields. Think of it as a README written for your AI instead of for a human. It was introduced alongside OpenAI's Codex and is now supported by Codex, Cursor, Aider, Cline, Windsurf, and others — with Gemini CLI requiring a GEMINI.md symlink as described below. A good one leads with commands, because the agent refers back to them constantly:
# Project: Acme API
## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test (run before every PR): `pnpm test`
- Lint & typecheck: `pnpm lint && pnpm typecheck`
## Conventions
- TypeScript strict mode. Never use `any`.
- Do not edit files in `/generated` — they are built from schemas.
- Write a test for every new endpoint.Here is the one wrinkle on the Claude side. Anthropic's tool uses its own file, CLAUDE.md, and as of mid-2026 Claude Code does not read AGENTS.md natively — a gap the community has been loudly requesting for months. The portable move is to keep one source of truth in AGENTS.md and point the others at it with a symlink, so you never maintain the same rules twice:
# One canonical file, linked everywhere your tools look
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.mdOne file, every tool, zero duplication. One caution worth knowing: do not blindly auto-generate this file and walk away. Research has consistently shown that bloated, auto-generated instruction files tend to hurt more than they help — the important rules get buried in noise and the agent learns to half-ignore them. Keep it short, hand-curated, and honest about what is genuinely non-obvious.
Agent Skills — teach once, reuse everywhere
The third standard is the one that feels like magic the first time it clicks. An Agent Skill is a folder containing a SKILL.md file — Markdown instructions for a specific task — plus any optional scripts or reference docs that task needs. Anthropic's own framing is the clearest: building a skill is like writing an onboarding guide for a new hire. You capture how to do something once, and the agent follows it forever after.
The clever part is progressive disclosure. At startup the agent only reads each skill's name and one-line description — a few dozen words — so a hundred skills cost almost nothing. Only when a task actually matches does it open the full instructions, and only then does it reach for the bundled scripts. Your context window stays clean until the moment a skill is relevant.
pdf-form-filler/
├── SKILL.md # name + description + instructions
├── scripts/ # code the agent runs (stays out of context)
│ └── fill.py
├── references/ # long docs, loaded only when needed
└── assets/ # templates, fonts, iconsBecause a skill is just Markdown and files in a folder, it is inherently portable — you can point Codex or Gemini CLI at a skills folder, tell it to read the SKILL.md, and it simply works. Agent Skills are now supported across a growing list of tools: Claude Code, Codex, Cursor, Gemini CLI, and more. Write your "how we deploy" or "how we write migrations" skill once, and it travels.
So when do you reach for which? They are not competitors; they answer different questions. Here is the cheat sheet:
Mechanism |
What it gives the agent |
Reach for it when |
|---|---|---|
Agent Skill |
A repeatable procedure — the how |
You keep re-explaining the same multi-step workflow |
MCP server |
A connection to an outside system — the reach |
The agent needs live data or a third-party API |
Subagent |
A fresh worker with its own clean context |
A job is large, or you want an independent reviewer |
AGENTS.md |
Always-on project facts and rules |
Conventions every session should already know |
Hook |
Enforcement that always runs, no exceptions |
Something must happen — formatting, blocking secrets |
Does "switch tomorrow" actually hold?
It is a fair thing to be skeptical about — a portability promise is only as good as the tools honoring it. So here is an honest snapshot of where the major agents stood in mid-2026 on all three standards. It is not perfect across the board, but it is good enough that moving your setup is a copy-and-tweak job, not a rebuild.
Agent |
MCP |
AGENTS.md |
Agent Skills |
|---|---|---|---|
Claude Code |
Yes |
Via CLAUDE.md / symlink |
Yes, native |
OpenAI Codex |
Yes |
Yes (its home format) |
Yes |
Cursor |
Yes |
Yes |
Yes |
Windsurf |
Yes |
Yes |
Yes |
Zed |
Yes |
Yes |
Via hosted agents |
Aider |
Limited |
Yes |
Via conversion |
Cline |
Yes |
Yes |
Yes |
Gemini CLI |
Yes |
Yes (GEMINI.md) |
Yes |
The weak spots are real and worth naming — Aider's MCP support is limited, and a few tools only run skills through their cloud agents — but the spine holds. Your tools, instructions, and skills are written in formats more than one vendor understands.
Your portable setup, layer by layer
Now let's assemble it. The trick is two tiers: one that lives with each project and travels in its Git repo, and one that is personal to you and follows you across every machine and every project.
Tier 1 — the project repo (commit this)
At the root of each project, keep an AGENTS.md as the single source of truth, with CLAUDE.md and friends symlinked to it. Add an .mcp.json for the tools that project needs (databases, issue trackers), with secrets pulled from environment variables. Put team-shared skills in a folder like .agents/skills/. Commit all of it. The payoff: a teammate — or you, six months later — clones the repo and the AI is instantly productive, with the same rules and the same tools, no setup call required.
Tier 2 — your personal dotfiles
Your personal taste — how you like commit messages written, your favorite skills, your global tool configs — belongs in a dotfiles repo you carry everywhere. The reliable pattern is to keep one canonical copy of each file and symlink it into the locations each tool expects, using a tiny helper so a fresh machine is set up in seconds:
safe_symlink() {
local src=$1 dst=$2
[ -L "$dst" ] && rm "$dst"
[ -e "$dst" ] && mv "$dst" "$dst.bak"
mkdir -p "$(dirname "$dst")"
ln -s "$src" "$dst"
}
safe_symlink "$DOTFILES/AGENTS.md" "$HOME/.claude/CLAUDE.md"
safe_symlink "$DOTFILES/AGENTS.md" "$HOME/.codex/AGENTS.md"
safe_symlink "$DOTFILES/skills" "$HOME/.claude/skills"Tools like GNU Stow and chezmoi exist to manage exactly this, and chezmoi is the kinder choice if you bounce between macOS, Linux, and Windows. One Windows gotcha to save you an hour: symlinks there need Developer Mode or admin rights and core.symlinks=true in Git, and mixing WSL and native-Windows symlinks does not work — pick one world and stay in it.
Advanced Claude Code moves that survive the move
Everything above keeps you portable. But within Claude Code there are sharper techniques worth knowing — and because they are built on the same standards and plain files, they travel with you too. The single mental model that explains most of them: Claude's context window fills up fast, and quality drops as it fills. Almost every good habit is really about protecting that space.
Subagents are separate Claude instances with their own clean context and their own narrow tool permissions. Hand a big exploration or an independent code review to a subagent, and only its summary comes back — your main conversation stays uncluttered. A favorite pattern: after a long stretch of work, spin up a fresh reviewer subagent that sees only the final diff and the requirements, with no memory of the messy path that got there.
Slash commands and hooks are where you encode habits. A custom command is a saved prompt you trigger by name. A hook is different and more powerful: it is a script that fires automatically at a set moment — and this is the key distinction — your instruction files only suggest behavior, while a hook guarantees it. Want code formatted every single time a file is written, no exceptions?
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "pnpm prettier --write \"$CLAUDE_FILE_PATHS\"" }]
}
]
}
}Plan mode is the antidote to an agent that charges off in the wrong direction. Toggle it and Claude reads, analyzes, and proposes a plan without touching your files. The workflow Anthropic recommends is simple and worth internalizing: explore, plan, implement, commit — in that order, with your eyes on the plan before any code is written.
Worktrees and headless mode are for scale. Git worktrees let you run two to four Claude sessions in parallel on separate branches without collisions. Headless mode — the much-missed claude -p flag — turns Claude into a command-line citizen you can pipe into and wire into CI:
# Pipe an error log straight into a headless review
cat error.log | claude -p "Find the root cause and propose a fix"
# CI-safe: cap turns and restrict tools
claude -p "Run the test suite and fix failures" \
--max-turns 12 \
--allowedTools "Bash(pnpm test:*)" "Edit"And one underused habit: ask Claude to explain its reasoning as it works — add "and briefly explain each decision" to your prompt. You absorb the why as you read the diff, not just the what. For a new codebase, this single habit is worth the extra few lines of output.
If you are a vibe coder, start here
If the section above felt like a lot, this part is for you. Vibe coding — building by describing and steering rather than hand-writing every line — is a real and legitimate way to ship. But there is an honest catch worth saying plainly: the impressive demo is the easy 80%. The boring 20% — real authentication, a real database, payments, deployment, security — is where projects quietly fall apart. Security researchers scanning AI-assisted apps throughout 2025 found troubling rates of exposed credentials — API keys hardcoded in frontends, admin passwords committed to public repos — almost all of it preventable with a single review step.
So here is the short, high-leverage starter kit. None of it slows you down much, and all of it keeps you out of the ditch:
Treat the AI like a sharp junior engineer with tools, not a magic box. Build features in layers — get auth working, then the database, then payments — rather than asking for everything in one breath.
Give it a role that changes its priorities. "Act as a senior engineer who has been burned by sloppy payment code" produces noticeably more careful, defensive work.
Always run an adversarial reviewer at the end — a fresh subagent that sees only the diff and is asked to find what is wrong. This one habit catches most of those exposed-secret disasters.
Do not launch Claude Code from your home folder — it then has reach over your SSH keys and tokens. Work inside a dedicated project folder.
Turn on the "Learning" output style and let the tool explain itself. You will absorb the why, not just collect the what.
You do not need a 10-monitor battlestation to build well — you need good defaults. Photo by Jakub Żerdzicki on Unsplash.
Anti-patterns to skip
A few traps catch nearly everyone. Knowing them in advance saves real time:
Instruction-file bloat. A giant
AGENTS.mdbackfires — the important rules get lost in the noise and the agent half-ignores them. For each line, ask whether removing it would cause a mistake. If not, cut it.MCP overload. Connecting fifteen servers globally floods the agent with tool options and it starts picking wrong. Add tools per project, only where they earn their place.
No way to check the work. This is the big one. If you do not give the agent a test, a build, or a linter it can run, it stops when the code merely looks done — and you become the error-checker. Give it a check it can run, and have it show you the passing output rather than just claiming success.
Rules where guarantees belong. "Always format the code" written in an instruction file is a suggestion it may drop. If it must happen, make it a hook.
Keeping it all to yourself. If your
.mcp.jsonand shared skills are not committed, your teammates are flying blind. Portability includes your team.
The point
The best Claude Code setup is not a clever pile of configuration locked inside one app. It is a small, portable kit — instructions in AGENTS.md, tools behind MCP, know-how in Skills — written in open formats you own and can carry anywhere. Build it that way and you are not betting on which agent wins the next release cycle. You are making that question stop mattering, because whatever you reach for tomorrow, your setup is already waiting for you there.
You can start in the next ten minutes. Write a short, honest AGENTS.md for your current project. Symlink CLAUDE.md to it. Then take the one workflow you keep re-explaining to your AI, and move it out of your head and into a SKILL.md. That is the whole foundation — and it already belongs to you.
Top comments (0)