AgentCard vs agent.json vs SKILL.md: Agent Identity Files Explained

Agent identity is starting to look less like a profile page and more like an operating record.

As AI agents become discoverable, callable, payable, and integrated into real workflows, they need more than a name inside one app. They need structured metadata, readable instructions, trusted endpoints, verification signals, and a stable place where those records can live.

That is where three files or formats keep appearing in the conversation: AgentCard, agent.json, and SKILL.md.

They are related, but they are not the same thing.

An AgentCard can help another agent or client discover what an agent supports in a specific ecosystem such as A2A. An agent.json file can act as a structured identity manifest that describes the agent, its capabilities, endpoints, permissions, verification data, and payment metadata. A SKILL.md file can explain what the agent does, how it should be used, and what instructions or workflows apply.

The useful model is not “which file wins?” The useful model is this:

Agent identity needs both machine-readable and human-readable layers, anchored to a persistent namespace that can be discovered and verified across the agentic web.

Why agent identity needs more than one file

A human can read a profile and understand the basics: name, description, owner, links, and purpose. Agents need more structure. They need to know where to send requests, what actions are allowed, what authentication is required, what the agent claims to do, and whether the record can be trusted.

That creates a layered identity problem.

• Discovery layer: How does another system find this agent and understand its supported interfaces?
• Manifest layer: Where is the structured identity record for the agent?
• Instruction layer: How should humans and agents understand what the agent does and how to use it?
• Namespace layer: Where does this identity live so it is not trapped inside one app, session, or marketplace?

These layers are why AgentCard, agent.json, and SKILL.md should be treated as complementary building blocks instead of interchangeable labels.

This also connects directly to the broader Headless Domains thesis. In The New Business Unit Is the Agent, the argument is that agents need identity continuity because they are beginning to perform real tasks across discovery, execution, support, renewal, and relationship workflows. A temporary chat session can answer a question. A persistent agent identity can participate in a workflow.

What is an AgentCard?

An AgentCard, often written as “Agent Card” in A2A documentation, is a discovery object for an agent. In the Agent2Agent ecosystem, it describes what an agent is, what capabilities it exposes, how it can be reached, what authentication it requires, and what skills or interfaces it supports.

The current A2A specification describes agent discovery through an Agent Card and documents /.well-known/agent-card.json as the discovery path. You can read the A2A specification here: A2A Protocol specification.

There is an important nuance. Some A2A tutorials and implementations still show an Agent Card being served from /.well-known/agent.json. For example, Google’s A2A codelab describes an agent card available at /.well-known/agent.json. You can see that implementation example here: Google A2A codelab.

That means the article should avoid saying “AgentCard is always located at one path” without context. A safer statement is:

AgentCard is a confirmed discovery concept in A2A, but endpoint naming has varied across versions and implementations. Check the current spec and the ecosystem you are integrating with.

What an AgentCard can include

• Agent name
• Description
• Service URL or endpoint
• Supported input and output modes
• Capabilities
• Skills
• Authentication requirements
• Protocol version
• Provider or operator metadata

Think of AgentCard as an interoperability surface. It helps another agent or client understand how to communicate with this agent in an ecosystem-specific way.

What is agent.json?

agent.json is best understood as an emerging implementation pattern for a structured agent identity manifest. Unlike the A2A Agent Card, it should not be described as one universal standard unless you are referring to a specific project, spec, or implementation that defines its own schema.

In a Headless Domains context, agent.json can describe the persistent identity record for an agent. It can answer questions like:

• What is this agent called?
• Who controls or operates it?
• What does it claim to do?
• What capabilities does it expose?
• What endpoints can approved systems call?
• What permissions does it require?
• What verification records are available?
• What payment or billing metadata applies?
• Where is the matching SKILL.md?
• Where is the public directory profile?

That makes agent.json more like an identity manifest than a marketing page. It gives agents, apps, directories, and marketplaces a structured way to inspect the agent before routing work, calling an endpoint, granting access, or initiating payment.

This is especially important before listing an agent in a marketplace. The Agent Marketplace Identity Checklist recommends publishing agent.json, SKILL.md, MCP endpoints, payment metadata, verification links, support contacts, renewal logic, and a directory profile before an agent is listed, hired, integrated, or paid.

Example agent.json fields

{
  "name": "example.agent",
  "description": "A short description of what this agent does.",
  "identity": {
    "namespace": "example.agent",
    "canonical_url": "https://example.agent"
  },
  "controller": {
    "organization": "Example Company",
    "contact": "support@example.com"
  },
  "capabilities": [
    "support",
    "catalog_lookup",
    "order_status"
  ],
  "endpoints": {
    "api": "https://api.example.com/agent",
    "mcp": "https://mcp.example.com"
  },
  "permissions": {
    "requires_auth": true,
    "allowed_actions": [
      "read_order_status",
      "create_support_ticket"
    ]
  },
  "verification": {
    "profile": "https://directory.headlessprofile.com/example.agent",
    "support_url": "https://example.com/support"
  },
  "related_files": {
    "skill": "https://example.agent/SKILL.md",
    "agent_card": "https://example.agent/.well-known/agent-card.json"
  }
}

This is an implementation example, not a universal schema. The important point is that agent.json gives the agent identity a structured record that software can inspect.

What is SKILL.md?

SKILL.md is a markdown-based instruction file used in agent skill systems. It is usually human-readable, but it is also written so agents can load and follow the instructions.

OpenAI describes a skill as a versioned bundle of files plus a SKILL.md manifest containing front matter and instructions. You can read the OpenAI Skills documentation here: OpenAI Skills documentation.

Microsoft’s Agent Framework documentation also describes Agent Skills as portable packages of instructions, scripts, and resources that follow an open specification and use a progressive disclosure pattern. You can read Microsoft’s documentation here: Microsoft Agent Skills documentation.

In practical terms, SKILL.md explains how to use a capability. It is not the same thing as an identity manifest. It should tell humans and agents what the skill or agent does, when to use it, what inputs are needed, what outputs to expect, and what constraints apply.

What SKILL.md can include

• Skill or agent name
• Description
• When to use it
• When not to use it
• Required inputs
• Expected outputs
• Step-by-step workflow
• Examples
• Limitations
• Security notes
• Support or escalation instructions

Where agent.json says “what this agent is and where its trusted records live,” SKILL.md says “how this agent or skill should be used.”

AgentCard vs agent.json vs SKILL.md

Format	Status	Primary purpose	Best contents	What it is not
AgentCard	Confirmed in A2A, ecosystem-specific elsewhere	Discovery and interoperability	Agent name, URL, capabilities, skills, supported modes, authentication, protocol version	Not a full persistent identity namespace by itself
agent.json	Emerging implementation pattern	Structured agent identity manifest	Identity, controller, capabilities, endpoints, permissions, verification, payment metadata, related files	Not one universal agent standard across every ecosystem
SKILL.md	Used in Agent Skills ecosystems	Readable operating instructions	Description, usage rules, workflows, examples, constraints, resources, escalation notes	Not a protocol discovery card or complete identity manifest

How they work together

The strongest agent identity setup does not force one file to do everything. It uses each layer for the job it is best suited to perform.

AgentCard helps other agents discover how to interact

In an A2A environment, an AgentCard can help another agent discover available capabilities and understand how to communicate. It is useful when agents need to find each other, negotiate supported modes, and route tasks across systems.

agent.json gives the identity structure

agent.json can act as the persistent structured record. It can describe the agent’s canonical identity, controller, endpoints, verification data, payment metadata, directory links, and related files. This gives marketplaces, applications, and other agents a stable way to inspect the agent outside a single listing page.

SKILL.md explains how the agent should be used

SKILL.md gives the operational guidance. It can explain what the agent does, when to use it, what inputs are required, and what workflows to follow. This is helpful for humans, developers, and agents that need readable instructions before taking action.

How they fit into a persistent .AGENT identity

A persistent .AGENT identity can act as the anchor for these files.

The files describe the agent. The namespace gives those descriptions a stable place to live.

Without a persistent namespace, an agent’s identity can become fragmented across app profiles, marketplace listings, chat sessions, API dashboards, and private repositories. One marketplace might have a listing. Another tool might have a connector. A developer might have a README. A payment provider might have billing metadata. None of those alone becomes the agent’s persistent source of truth.

A .AGENT identity can connect those records into one inspectable identity layer:

example.agent
├── agent.json
│   ├── identity
│   ├── controller
│   ├── capabilities
│   ├── endpoints
│   ├── permissions
│   ├── payment metadata
│   ├── verification
│   └── related files
│
├── SKILL.md
│   ├── what this agent does
│   ├── when to use it
│   ├── workflows
│   ├── examples
│   ├── constraints
│   └── escalation rules
│
└── AgentCard
    ├── supported protocol
    ├── service endpoint
    ├── skills
    ├── supported modes
    ├── authentication
    └── capabilities

This is where Headless Domains fits. Headless Domains gives autonomous agents a persistent, verifiable identity record that can be discovered, trusted, and reached across tools, sessions, marketplaces, and platforms.

That matters because the agentic web is not only about creating more agents. It is about making those agents understandable, inspectable, reachable, and trustworthy when they act.

Where MCP fits

The Model Context Protocol, or MCP, is another important part of the agent infrastructure stack, but it solves a different problem.

MCP gives applications and agents a standardized way to connect to tools, resources, prompts, and external systems. The official MCP specification describes resources, tools, prompts, authorization, transports, and other protocol requirements. You can read the MCP specification here: Model Context Protocol specification.

MCP can help an agent use tools. It does not automatically answer every identity question.

Before an agent calls a tool or grants access to a workflow, it may still need to know:

• Who controls this agent or server?
• What identity record should be trusted?
• Where are the public verification signals?
• What permissions are being requested?
• What support or security contact exists?
• What payment metadata applies?

That is why MCP, AgentCard, agent.json, SKILL.md, and .AGENT should be viewed as complementary layers.

Technical implementation notes

1. Do not treat every file as the same file

A common mistake is to collapse every concept into a single “agent metadata file.” That makes implementation harder to reason about.

Use clearer separation:

• Use AgentCard for A2A discovery and interoperability where A2A is supported.
• Use agent.json for structured identity metadata and verification pointers.
• Use SKILL.md for readable instructions, workflows, and operating guidance.
• Use .AGENT as the persistent namespace where those records can be anchored.

2. Document your discovery paths

Because implementations vary, document where each record lives. For example:

• https://example.agent/agent.json
• https://example.agent/SKILL.md
• https://example.agent/.well-known/agent-card.json

If your ecosystem expects a different well-known path, document that explicitly and link to the relevant spec or implementation guide.

3. Add versioning

Every structured identity record should include versioning fields where possible:

• version
• schema_version
• last_updated
• canonical_url
• controller
• related_files

Agents need to know whether they are reading a current record or stale metadata copied from an old listing.

4. Keep public and private records separate

Public identity files should help people and agents verify the identity, understand capabilities, find support, and route requests safely.

They should not expose secrets.

Do not publish:

• Private keys
• API secrets
• Internal credentials
• Hidden system prompts
• Private customer data
• Unprotected admin endpoints
• Security-sensitive implementation details

For production agents, consider separating public discovery metadata from authenticated extended metadata.

5. Connect identity to directory discovery

A persistent identity is stronger when it can be inspected through a public directory or profile surface. That is why a .AGENT identity should connect to a public profile, support page, verification record, and any approved marketplace listings.

This is especially important for marketplaces. As explained in Why Agent Marketplaces Need Persistent Identity, a marketplace listing helps with discovery, but persistent identity helps with inspection, trust, and continuity across tools and platforms.

Practical examples

Example 1: A public support agent

A company publishes support.agent.

• agent.json declares the official company, support endpoints, escalation policy, authentication model, and verification links.
• SKILL.md explains what the support agent can help with, what information it should never request, and when to escalate to a human.
• AgentCard supports A2A discovery if the support agent participates in agent-to-agent workflows.

Example 2: A marketplace-listed agent

A productivity agent is listed in multiple agent marketplaces.

• AgentCard helps compatible systems discover what the agent supports.
• agent.json lists canonical identity, marketplace URLs, controller details, payment metadata, and support endpoints.
• SKILL.md explains how users and agents should invoke it.
• The .AGENT namespace becomes the persistent identity that all listings point back to.

Example 3: A commerce agent

A merchant creates an agent-readable shopping assistant.

• agent.json includes catalog pointers, checkout endpoints, supported payment metadata, policy URLs, and verification links.
• SKILL.md explains how agents should search products, compare variants, respect policies, and route support.
• AgentCard can expose supported interaction modes for agent-to-agent commerce.

Example 4: An MCP-enabled developer tool

A developer tool exposes an MCP server for repository analysis.

• MCP exposes the tool interface.
• agent.json describes the identity, controller, endpoint, permissions, and verification record.
• SKILL.md explains safe usage, expected inputs, and review workflow.
• A .AGENT identity makes the tool easier to discover and verify outside one client.

The bottom line

AgentCard, agent.json, and SKILL.md are not rivals.

They describe different parts of the same agent identity problem.

• AgentCard helps agents discover how to interact in an ecosystem such as A2A.
• agent.json gives the agent a structured identity manifest.
• SKILL.md gives humans and agents readable operating instructions.
• .AGENT gives those records a persistent namespace so they are not trapped inside one marketplace, app, or session.

The agentic web needs agents that can be discovered, verified, reached, trusted, and understood. That requires more than a profile card. It requires an identity record.

Give your agent a persistent identity, publish the files that explain what it does, and make the record inspectable before other agents, apps, marketplaces, or buyers depend on it.

Explore Headless Domains and give your agent a trusted identity for the agentic web.