Share project instructions across Claude Code and Codex

Two agents can see the same repository without reading the same instruction files or inheriting one another's tools. Share the facts and the task outcome first; configure each CLI's instructions and connections deliberately.

Keep project facts in ordinary repository files

Put architecture, run commands, test commands, and API contracts in maintained README or docs files. These are inspectable by a teammate and by any coding CLI with access to the checkout. Put the current task's branch, acceptance checks, changed files, test results, and next action in a short handoff. A shared repository is a better source of truth than asking the second model to infer decisions from a long private chat transcript.

Check which instruction files this CLI actually loaded

Codex uses AGENTS.md as a repository instruction surface. Current Claude Code documentation says versions 2.1.277 and later can also read AGENTS.md directly when no project-path CLAUDE.md or CLAUDE.local.md takes precedence; its Project instructions setting can change that choice. Older versions and some session modes may need a CLAUDE.md with an @AGENTS.md import. Keep shared facts in maintained docs and use a short import or CLI-specific section only when needed. In a fresh Claude session, check /memory for the loaded path and confirm the version; in a fresh Codex session, inspect its reported project instructions and ask it to identify one repository constraint. Canopy hosts the CLI but does not decide its file discovery.

Reserve skills for repeatable work

A skill is a focused set of instructions and optional resources for a recurring task such as reviewing a database migration or drafting a release note. Both ecosystems document SKILL.md-based skills, but discovery, invocation, and surrounding tooling can differ. Review a skill's commands and assumptions before making it available to a second CLI. Keep the description narrow so agents load it for the right task, and link to supporting files only when needed; large always-on instructions add context without helping every request.

Use MCP when the agent needs a live system

MCP servers expose tools or current data, such as documentation search or a ticket system. A skill can say how to use those tools; it does not create the connection or grant access. Configure and authorize MCP separately in the CLIs that need it. Canopy's current-main documentation describes discovery and inspection of MCP servers across supported CLI configurations; verify the installed release and do not treat a discovered server as permission to copy credentials to another agent or teammate.

Hand off one bounded task

Pause the first agent at a stable branch or commit. Give the second CLI the outcome, checkout, relevant docs, changed files, evidence, and one next action. If it will review, keep it read-only until it returns specific findings. If it will implement, decide who owns the worktree before editing. Canopy can keep project and session context visible around both, but each CLI still owns its conversation, models, account, and available tools.

Check for instruction drift

Once a month or after a repeated agent mistake, remove obsolete commands, duplicate guidance, and conflicting rules. A stale README and two contradictory agent files can cost more time than a missing instruction. Test both CLIs on a small, reversible task after changing their setup, and record the behavior you actually observed rather than claiming full cross-CLI parity.

Copyable resources

Copyable cross-CLI instruction plan

Adapt paths to your repository and verify the loaded files in fresh sessions.

README.md / docs/: canonical run commands, architecture, and API contracts
AGENTS.md: short shared project instructions for Codex and supported Claude Code setups
CLAUDE.md: use when Claude-specific content or an @AGENTS.md import is needed
Skills: one focused repeatable workflow per skill; test invocation in each CLI
MCP: configure and authorize live tools separately in each CLI
Task handoff: goal, acceptance checks, branch, changed files, tests, decisions, next action
Fresh-session check: inspect loaded instruction paths and ask each CLI for the run command and one constraint.

Frequently asked questions

Will Claude Code read my AGENTS.md?

Current Claude Code versions can read it directly in documented setups, but a project-path CLAUDE.md can take precedence. Check your version, Project instructions setting, and /memory in a fresh session. Canopy does not change this discovery.

Are a skill and an MCP server the same thing?

No. A skill gives reusable instructions and resources. An MCP server supplies a connection to tools or live data, with its own configuration and access boundary.

Do shared skills or context share a paid model account?

No. Claude Code and Codex retain their own accounts, models, usage limits, and provider billing.

Browse more Canopy questions →