DEV Community

Cover image for Onboard AI agents like you onboard devs
Dimon
Dimon

Posted on

Onboard AI agents like you onboard devs

#agentskills #agents #ai

When new devs join a project, someone walks them through the conventions - where things live, what the house rules are, which commands to run. AI agents get none of that. Every session starts context-blind, and an agent that finds no instructions doesnt ask - it guesses. Recent surveys say that most engineers now use 2-4 AI tools at once. If you have more than a couple of devs, you effectively have a multi-agent repo whether you planned it or not. So the question isnt whether to write onboarding docs for agents - its which ones, because they read different files.

Tier 1 — mandatory.

Two files:

  • AGENTS.md — the cross-tool standard, Linux Foundation-hosted since Dec 2025, read natively by Codex, Copilot's coding agent, Cursor, Windsurf and roughly two dozen other tools. Content: stack, commands, hard rules, pointers to deeper docs. Keep it under ~200 lines.

  • CLAUDE.md — exists solely because Claude Code (the most-used agent in recent surveys) is the one major tool that doesn't read AGENTS.md. Anthropic's own recommended bridge: first line '@AGENTS.md' (Claude Code expands the import at session start), with Claude-specific notes below. So the mandatory setup is two files, and one is a pointer.

If you have multi-step workflows worth teaching (release process, scaffolding recipes), add skills: the SKILL.md format went cross-vendor after Anthropic opened the spec, and the same folder now loads in Claude Code, Codex, VS Code and Gemini CLI. Only quirk: Claude Code looks in .claude/skills/, Codex in .agents/skills/ — mirror one to the other and move on.

Tier 2 — do it if the tools are actually in your org.

Copilot and Cursor both read AGENTS.md, so this tier buys optimization, not coverage:

  • Copilot — .github/copilot-instructions.md for in-editor chat; .github/instructions/*.instructions.md for applyTo-scoped rules.

  • Cursor — .cursor/rules: the auto-attach-by-glob rule type is the real feature. Conventions load only where they apply.

No Copilot seats, no Cursor users → skip the tier entirely.

Tier 3 — nice-to-have.

  1. MCP server — if you have machine-readable assets (tokens, registries, schemas), agents query live data instead of grepping stale prose.

  2. Gemini CLI — reads GEMINI.md by default, but a checked-in .gemini/settings.json can point context.fileName at AGENTS.md (config beats another markdown file).

  3. Portable system-prompt doc — for raw-API callers and eval harnesses; derive it from AGENTS.md.

The part that actually matters: dont hand-maintain these files. They will drift, and a wrong instruction file is worse than none because the agent trusts it and never double-checks. Generate every surface from one source of truth with a dumb deterministic template script (no LLM in the build), so re-runs are byte-stable - CI regenerates everything and fails on any diff.

This whole thing is accidental complexity tho. There are two real standards now: AGENTS.md for context, SKILL.md for workflows. Most of the per-tool files exist just because vendors shipped their own filename before agreeing on anything.

Top comments (0)