Chapter 78 — Agent interop: AGENTS.md, Skills, MCP, and A2A

The map

                          +-----------------------+
     AGENTS.md  --------> |                       | <-------- Skills
     "how we work here"   |        AGENT          |   "how to do X",
     (read at start)      |   (model + harness)   |   loaded on demand
                          |                       |
                          +---+---------------+---+
                              |               |
                         MCP  |               |  A2A
            tools, data,      |               |   other AGENTS, as peers:
            prompts           v               v   discover, delegate, track
                     +-------------+    +----------------+
                     | MCP servers |    | remote agents  |
                     | (Part 13)   |    | (other vendors,|
                     +-------------+    |  other teams)  |
                                        +----------------+

AGENTS.md: a README for agents

A plain Markdown file at the root of a repository (optionally more in sub-folders, where the nearest one wins) with the things a new engineer would need on day one: build and test commands, code style, project layout, and what not to touch. Introduced by OpenAI and adopted by many coding agents in 2025, it's now stewarded by the Agentic AI Foundation (below).

# AGENTS.md

## Setup
- `pnpm install`; Node 22. Never use npm or yarn here.

## Test
- `pnpm test` for unit tests; `pnpm e2e` needs `docker compose up db` first.
- A change is done only when `pnpm lint && pnpm test` passes.

## Conventions
- API handlers live in `src/routes/`; one file per resource.
- Never edit `src/generated/` -- run `pnpm codegen` instead.
- Migrations are append-only. Never modify an existing file in `migrations/`.

## Safety
- Do not run anything against `*.prod.internal` hosts.

Why it matters: it's the project rules layer of the harness (Chapter 74), in a format every agent reads. Keep it short and factual: it's injected into context on every session, so every line costs tokens on every call. Agents that support their own file name (such as CLAUDE.md) can simply point it at AGENTS.md so you maintain one file.

Skills: playbooks the agent loads only when needed

A skill is a folder containing a SKILL.md file (instructions with a short YAML header) plus any scripts, templates, or reference files it needs. Anthropic introduced Agent Skills in October 2025 and published the format as an open standard that December, and other agents have adopted it since.

   skills/
     release-notes/
       SKILL.md              <- name, description, step-by-step instructions
       template.md           <- referenced from SKILL.md, read only if needed
       scripts/collect_prs.py

---
name: release-notes
description: Write user-facing release notes from merged PRs since the last
  tag. Use when asked to prepare a release or changelog.
---

1. Run `python scripts/collect_prs.py --since $(git describe --tags --abbrev=0)`.
2. Group PRs into Features / Fixes / Breaking changes using their labels.
3. Fill in `template.md`. Write for customers, not engineers: no PR numbers
   in the prose, one sentence per change, breaking changes first.
4. Show the draft to the user before writing it to `CHANGELOG.md`.

The key design idea is progressive disclosure, which is exactly the harness trick from Chapter 74:

   always in context:   name + description       (~30 tokens per skill)
   when relevant:       the body of SKILL.md     (loaded by the agent)
   only if needed:      template.md, scripts     (read or executed)

So an agent can have 200 skills installed for the cost of 200 short lines.

Skill vs MCP server vs AGENTS.md, the question everyone asks:

Security note: a skill can contain executable scripts and instructions the agent will follow. Treat third-party skills like third-party code: read them before installing, and prefer trusted sources. Chapter 59's tool poisoning applies directly.

MCP: tools and data (recap)

Part 13 covered MCP in depth: hosts, clients, servers, and tools, resources, and prompts over JSON-RPC. Two 2025–26 developments matter here:

• Anthropic donated MCP to the Agentic AI Foundation (AAIF), formed under the Linux Foundation in December 2025 with founding projects MCP (from Anthropic), goose (an open-source agent framework from Block), and AGENTS.md (from OpenAI), and backed by the major AI labs and cloud providers.
• The spec kept evolving toward production needs: better authorization, remote servers, and the stateless transport described in Chapter 57.

A2A: agents talking to agents

MCP treats the thing on the other end as a tool: the agent calls it and gets a result. But sometimes the thing on the other end is itself an agent: it has its own model and tools, it may take hours, it may need to ask questions, and it belongs to someone else (a supplier, another team, another vendor). That's what A2A (Agent2Agent) is for. Google announced it in April 2025 and donated it to the Linux Foundation in June 2025, with backing from AWS, Cisco, Microsoft, Salesforce, SAP, ServiceNow, and others.

Core concepts:

• Agent Card: a JSON document a remote agent publishes (conventionally at /.well-known/agent-card.json) describing what it can do (its "skills"), its endpoint, and how to authenticate. That's discovery.
• Task: the unit of work, with a lifecycle (submitted → working → input-required → completed / failed / canceled), so long-running jobs and back-and-forth questions are first-class.
• Messages and artifacts: the conversation parts, and the outputs (files, structured data) the remote agent produces.
• Built on ordinary web standards: HTTP, JSON-RPC, and streaming via server-sent events, with push notifications for long tasks.

{
  "name": "Acme Freight Quoting Agent",
  "description": "Quotes and books LTL freight shipments within the EU.",
  "url": "https://agents.acme-freight.example/a2a",
  "version": "2.1.0",
  "capabilities": {"streaming": true, "pushNotifications": true},
  "skills": [
    {"id": "quote", "name": "Get a freight quote",
     "description": "Price a shipment given origin, destination, pallets, weight."},
    {"id": "book", "name": "Book a shipment",
     "description": "Book a previously quoted shipment. Requires a quote_id."}
  ],
  "securitySchemes": {"oauth": {"type": "oauth2"}}
}

MCP vs A2A in one line: MCP is how an agent uses a tool; A2A is how an agent hires another agent. A procurement agent would use MCP to read your ERP, and A2A to ask a supplier's agent for a quote. Field note: in 2026 MCP is everywhere, while A2A adoption is concentrated in enterprise platforms and cross-company workflows. Many teams never need it, because most "multi-agent" systems live inside one codebase where a function call is simpler (Chapter 54).

A real-world example: one request, every standard

A developer asks their coding agent: "Ship the date-picker fix and prepare release notes."

1. The agent starts by reading AGENTS.md: test command, never edit src/generated/.
2. It fixes the bug, and the harness's post-hook runs the tests (Chapter 74).
3. It sees from the skill index that release-notes matches, loads that SKILL.md, and runs its collect_prs.py script.
4. It uses the GitHub MCP server to open the pull request and the Jira MCP server to move the ticket to "In review".
5. The company's deployment is owned by a platform team's agent, so the coding agent sends an A2A task to the deploy agent: "deploy PR #4182 to staging", and streams status updates until the task completes.

Five systems, four standards, and no custom glue code written for this particular combination.

Computer use: when there's no API at all

Some systems have no API and no MCP server: legacy desktop apps, government portals, internal web tools. Computer-use (or browser-use) agents operate them the way a person does, from screenshots, clicking and typing. Anthropic, OpenAI, Google, and others all ship computer-use capabilities, and benchmarks like OSWorld and WebArena track progress. Rules of thumb: prefer an API or MCP server whenever one exists (it's faster, cheaper, and more reliable); run computer-use agents in an isolated VM or browser profile; and treat everything on screen as untrusted input, because web pages are a prime channel for prompt injection (Chapter 59).