Imported from kazhiramatsu/agent-handoff (SKILL.md). Install upstream with npx skills add kazhiramatsu/agent-handoff. Copyright stays with the author.

agent-handoff - one project context, every agent

Goal: any coding agent the user runs on this repo (Cursor/Fable, Codex, Copilot, Gemini CLI, Aider, Windsurf, Zed, Claude Code, ...) reads the SAME instructions, from ONE source, with no divergent copies to keep in sync.

The key fact (2026): AGENTS.md is the standard

AGENTS.md at the repo root is the cross-tool open standard (plain Markdown, no YAML frontmatter). Read natively by Codex, Cursor, Copilot Coding Agent, Gemini CLI, Windsurf, Aider, Zed, Amp, Devin, Jules, VS Code, JetBrains Junie, and ~28 tools. Claude Code reads it too (CLAUDE.md remains its richer native format). Agents read the NEAREST AGENTS.md up the directory tree, so subprojects can ship tailored ones.

So the modern shape is one AGENTS.md + thin per-tool shims, NOT N docs.

Procedure

1. Find or create the canonical content

• If a rich instructions file already exists (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, an existing AGENTS.md), treat its content as the seed - don't rewrite it, reuse it.
• Nothing exists yet: generate AGENTS.md DIRECTLY from the repo (like /init, but tool-agnostic). Do NOT write a separate deep playbook first - AGENTS.md is meant to be the concise, self-contained instruction file. Cover the AGENTS.md recommended sections, concise and command-first:
  • One-line what-this-project-is.
  • Setup / build - exact commands and flags (per subdir if needed).
  • Test / verify - how to run tests, lint, typecheck; what "green" means.
  • Code style / conventions that differ from defaults.
  • Project structure - where things live (a short map).
  • Boundaries - files/dirs the agent must NOT touch; generated artifacts.
  • Gotchas - the non-obvious traps (build quirks, env, platform). Keep it tight; link out to deeper docs rather than inlining everything. A deeper companion playbook (e.g. docs/agent_workflow.md with debugging recipes) is OPTIONAL - only worth it for a complex project, and only if the user asks; then keep AGENTS.md concise and pointing to it.

2. Make AGENTS.md the single source of truth

Pick ONE canonical file and point the others at it (zero drift):

• A rich CLAUDE.md already exists (e.g. Claude-first repos): keep CLAUDE.md canonical; make AGENTS.md a symlink to it: ln -s CLAUDE.md AGENTS.md Claude Code keeps using CLAUDE.md (richer); every other tool reads AGENTS.md = the same bytes. (CLAUDE.md is plain markdown, so it is valid AGENTS.md.)
• No canonical yet: write AGENTS.md as the real file; if the user also uses Claude Code, ln -s AGENTS.md CLAUDE.md (or keep a thin CLAUDE.md that adds only Claude-specific extras and says "see AGENTS.md").

Prefer symlinks over copies. If the OS/tooling can't follow symlinks (rare; some Windows setups, some CI checkouts), fall back to a one-line pointer file (See [AGENTS.md](./AGENTS.md).) and warn the user it can drift.

3. Wire the tools that want their OWN path

Ask which agents the user actually uses, then add only those shims. AGENTS.md already covers the natively-supporting tools (Codex, Cursor, Windsurf, Zed, Aider*, Amp, VS Code, Junie, ...). Extra hooks:

.cursor/rules/*.mdc is ONLY for granular rules (per-glob, auto-triggered) on top of the general AGENTS.md - not required just to give Cursor the project context. Don't add it unless the user wants scoped rules.

4. Report the result

Print a short table of "each tool now reads -> AGENTS.md (via X)", confirm the single-source/symlink so the user knows edits to the canonical propagate everywhere, and note anything that still needs a manual per-tool step (e.g. the Gemini settings.json, or a .cursor/rules if they wanted scoped rules).

Notes

• Commit the AGENTS.md + shims only if the user asks; symlinks are committable and travel with the repo.
• Re-running the skill should be idempotent: detect existing AGENTS.md / symlinks and sync rather than duplicate.
• Keep secrets and machine-specific paths OUT of AGENTS.md - it is shared context that ships with the repo.
• The spec + tool list live at https://agents.md/ - check it if a tool's support is uncertain.