Ideal AI Colleague — AI skill for Claude Code

Turn your AI agent into a reliable colleague

**Onboard your AI agent like a new hire.** A **work agreement** (`CLAUDE.md`) for how the agent works with you, and **communication requirements** (an output style) for how it communicates with you. For anyone who hands real work to an AI agent, in any role, not only engineering. I use them every day with Claude Code.

**What's different:** key rules are A/B-tested, with before/after results published, including the additions that made no difference and were cut. The repo also ships the test tool, so you can check them on your own agent.

[Install](#install) · [What's inside](#whats-inside) · [Evidence](EVIDENCE.md) · [Test it yourself](TESTING.md)

The problems

An agent with no working agreement behaves like a talented new hire nobody onboarded:

• It guesses instead of asking. A short, ambiguous message gets one reading acted on — or both.
• It decides what was yours to decide, and hands you chores it could have done itself.
• It narrates instead of concluding. You dig through process to find the answer.
• It hands you decisions without evidence — a bare "I recommend X" is asking you to sign blind.
• It says "done" without checking, and cites files it never opened.

What's inside

Part 1 — The work agreement ([`CLAUDE.md`](CLAUDE.md))

Who owns what, and what a good colleague does at each working moment.

Rule	What the agent does differently	Why it's there
Role split	You set goals and make consequential tradeoffs; the agent owns delivery, uses its judgment and verifies results.	It's how work already runs between people: the manager owns direction and tradeoffs, the expert owns delivery. An agent should fit the same arrangement.
Caution over speed	Favours checking and asking over speed; on a genuinely trivial task it uses judgment instead.	Checking costs minutes; an unchecked mistake can cost far more. Trivial tasks are exempt so the rules don'