Agent Card vs agent.json vs SKILL.md: Which Do You Need?

An A2A Agent Card describes how to interact with an A2A service. A Headless Domains agent.json manifest connects a named agent or service to its public information. A SKILL.md package gives a compatible assistant instructions for a task. They can describe the same offering, but a client cannot substitute one for another.

A customer might need a workflow guide while their application needs a protocol interface. Give each the document it can use, then connect those documents to a maintained headless domain.

Agent Card vs agent.json vs SKILL.md

You do not need all three to launch a useful service. Publish the records your intended clients need and can understand.

An Agent Card describes the A2A service

The A2A specification defines AgentCard as a structured discovery object. It describes the service, capabilities, skills, supported interfaces, and security requirements. Its supportedInterfaces entries identify connection URLs, protocol bindings, and versions.

Use the schema supported by your implementation. Publishing a card does not create the A2A server behind it.

The A2A discovery guide describes discovery through /.well-known/agent-card.json, catalogs, or direct configuration. The URL serving the card and the URL receiving task requests may be different.

If an integration uses another path, document it explicitly. A familiar filename is not enough to identify the format or select a parser.

agent.json needs a named schema

agent.json is a filename used by different implementations. It does not, by itself, identify one universal agent standard.

At Headless Domains, the manifest documentation describes hosted JSON and Markdown records, with TXT pointers to their locations. The manifest can describe capabilities and link to service information using the platform's supported structure.

Use that schema when publishing through Headless Domains. A custom JSON object containing sensible-looking fields is not automatically accepted by the platform or understood by another client.

The manifest gives compatible readers a way to inspect the named service and find its records. An A2A client still needs an A2A Agent Card to configure that particular interaction.

SKILL.md explains a procedure

The Agent Skills specification defines a skill directory containing SKILL.md. The file has YAML frontmatter with required name and description fields, followed by Markdown instructions. The directory may also contain scripts, references, and assets.

A compatible client must load the package through a supported mechanism. A website can also publish a readable workflow at a URL such as /skill.md, but fetching that page does not automatically install a package or provide its dependencies.

Preserve the exact filename and URL casing. A platform's getting-started guide, a domain's generated capability summary, and an installable skill package can all contain Markdown while serving different purposes.

For a working package example, use our SKILL.md guide.

An A2A skill is not an Agent Skills package

Inside an Agent Card, an A2A AgentSkill describes a capability offered by the remote agent. A SKILL.md package supplies instructions to the client that loads it.

A report-writing service might advertise “prepare a research report” in its card. A separate skill package could teach a customer's assistant how to gather the brief and review the returned report.

The two can work together. Listing a capability in the card does not install those instructions in the caller.

One named service, three useful views

Imagine briefreview.bpo, a fictional service that reviews project briefs. The name is illustrative; availability has not been checked.

Its public manifest describes the service and points to its approved information. A customer can use that record to locate the current documentation and contact route.

If the operator offers A2A access, its Agent Card describes the actual interface for submitting a review request. That interface could run on an ordinary HTTPS host such as https://review.example.com.

A skill package for the customer's assistant explains how to prepare the brief: identify the goal, collect the required constraints, remove information the service should not receive, and present the findings for human review.

The headless domain identifies the same offering across these records. The operator can move the documentation or change hosts while keeping the service name customers recognize.

Keep the files consistent as the service changes

Choose an authoritative source for each kind of information and document who maintains it. Protocol details belong in the implemented interface and its matching card. Workflow instructions should reflect that interface. The public identity record should lead to the current approved documents.

Before publishing an update, check:

• Identity: Do the records describe the same service and operator?
• Capabilities: Does the workflow ask for operations the service actually supports?
• Addresses: Are discovery documents distinguished from callable endpoints?
• Access: Do the instructions agree with the receiving service's authentication requirements?
• Versions: Can the intended client parse the card, manifest, and package versions provided?
• Changes: Have old links, cached records, and installed packages been accounted for?

Suppose the brief-review service stops accepting attachments. Update the callable interface, its description, and the preparation instructions together. A current card paired with an old installed skill can still send a customer down the wrong path.

Use version fields defined by the relevant format. Keep additional publication history in your own release records where needed. Adding arbitrary fields such as schema_version to every document does not make every client understand them.

What the files do not grant

Public documents describe a service and its requirements. They do not issue credentials, authorize spending, or enforce restrictions on a tool.

A signed Agent Card can support integrity and origin checks when the verifier trusts the signing key. It does not certify the agent's behavior. Similarly, instructions saying “ask before purchase” need to agree with the host and payment system's actual controls.

Keep tokens, private keys, customer data, and internal control details out of public records. If the documents disagree about a sensitive operation, resolve the mismatch with the operator before proceeding.

Where a headless domain adds value

Your service may have a card on one host, a skill package in a repository, and a profile in a directory. A headless domain gives that offering a maintained public name connecting its approved records.

The name can describe the work: .bpo for an operated process, .chatbot for a conversational service, or .factory for a production system. Headless Domains also offers namespaces including .agent, .boss, .protocol, and .manifest.

Publish links through supported record fields or linked documentation your clients understand. Keep the services on their existing hosts. Use the documented Headless Domains lookup and resolution routes rather than assuming the headless name is an ordinary browser URL.

As records move, update their references while maintaining the registration. Clients with saved endpoints or installed packages may still need an update; the name gives them a consistent place to find the current information.

Choose the document your caller needs

• An A2A client needs to connect: provide a valid card for the working A2A service.
• A reader needs to inspect the named offering: provide a public manifest using a documented schema.
• An assistant needs a repeatable procedure: supply a workflow guide or compatible skill package.

For documentation navigation, see llms.txt vs SKILL.md vs agent.json. If you are choosing the communication interface itself, use MCP vs A2A.

Give the service one name across its files

Start with the interface and instructions your customers use today. Connect those records to a headless domain, then maintain them as the service develops.

Send your assistant the Headless Domains machine instructions and ask it to explain how to register a suitable name and connect your existing public records.