agentic-resource-discovery

name

agentic-resource-discovery

description

Authoritative reference for the Agentic Resource Discovery (ARD) specification — the open, federated, domain-anchored standard (by Google, Microsoft, Hugging Face and others) for cataloging, discovering, and searching agentic resources (MCP servers, A2A agents, Skills, APIs, datasets, registries) across the web via ai-catalog.json manifests and a REST search interface. Use this skill whenever the user mentions ARD, "Agentic Resource Discovery", agenticresourcediscovery.org, ai-catalog.json, the urn:air: identifier scheme, Agent Finder, an "agent registry" or "discovery service", publishing/discovering/searching agents or tools, MCP/A2A catalog manifests, trustManifest / attestations / provenance for agents, the .well-known/ai-catalog.json path, federated agent search, or how agents/LLMs dynamically find capabilities at scale instead of hardcoding them — even if they don't name "ARD" explicitly. Also use when asked to author or validate an ai-catalog manifest, build an ARD client, stand up a registry, or connect Claude or Gemini to an Agent Finder.

Agentic Resource Discovery (ARD)

ARD is an open specification for publishing, discovering, and searching agentic resources across the web — so an AI client can ask "what is available for this task?" and a discovery service answers with matching, identity-verifiable resources. It is the discovery layer above execution protocols (MCP, A2A, Skills, APIs); it does not replace them and operates entirely before invocation.

• Status: v0.9 (Draft / Proposal), spec dated May 28 2026; announced by Google June 17 2026.
• Authors: Junjie Bu (Google), R.V. Guha (Microsoft), Shaun Smith (Hugging Face).
• Built on: the ai-catalog manifest standard. Apache 2.0.
• Canonical source of truth: the ards-project/ard-spec repo (spec/ard.md + spec/schemas/).

Use this skill to

Answer questions about ARD accurately, author/validate ai-catalog.json manifests, design or critique ARD registries and clients, explain how ARD relates to MCP / A2A / ANS / ai-catalog, or connect a chatbot (Claude, Gemini) to an Agent Finder. Ground answers in the reference files below rather than memory — ARD is post-cutoff and the details (URN scheme, media types, API shape) are precise and easy to get subtly wrong.

The mental model (read this first)

Four layers, bottom to top:

1. ai-catalog — the base, artifact-agnostic data model + trust/verification rules.
2. ARD — adds domain-anchored urn:air: identifiers, root-level capabilities, representative queries, and a mandatory REST search API with federation.
3. Agent Finder — the product brand (reference discovery services built on ARD).
4. Connectors — Skills / MCP connectors that wire Claude, Gemini, Copilot to finders.

Two complementary primitives — use either path independently, or both:

• Catalog (publish layer) — a static ai-catalog.json a publisher self-hosts on its own domain (/.well-known/), no central registration. An agent can read it directly.
• Registry (discovery layer) — an independent discovery service offering richer, governed, federated search via POST /search. It may or may not index catalogs; an agent queries it by intent and gets ranked matches. Catalog→registry indexing is optional.

The end-to-end lifecycle is ① PUBLISH → ② CRAWL (optional) → ③ SEARCH → ④ VERIFY → ⑤ CONNECT: host the catalog → a registry may index it → an agent queries a catalog or registry → it verifies publisher identity + Trust Manifest → it invokes the resource natively via MCP, A2A, or API. The defining principle: discovery only — trust is decided by the registry's curation and verified by the client, never asserted by the protocol itself.

The single most important design idea is the domain-anchored URN as a DNS-rooted, decentralized trust anchor (urn:air:<publisher-fqdn>:<namespace>:<name>), which solves namespace-squatting and identity verification without a central authority.

Critical accuracy note — docs lag the repo

The rendered docs site still shows two outdated identifiers. Always use the repo's current normative forms:

Topic	❌ Old (docs site)	✅ Current (repo, normative)	Why
URN NID	urn:ai:	urn:air:	ai is 2 chars; RFC 8141 requires NID ≥ 3 (ADR-0009)
MCP media type	application/mcp-server+json	application/mcp-server-card+json	It's a discovery card, not the live stream (ADR-0008)

Reference map — load only what the task needs

Each file is self-contained; read the one(s) relevant to the question rather than all.

• references/specification.md — The core normative spec. Read for anything about the data model (manifest structure, catalog entry fields, value-or-reference rule), the urn:air: identifier format + rationale, the trustManifest / attestations / provenance objects, the Registry REST API (POST /search, POST /explore, GET /agents, query/filter model, scoring), federation modes (auto/referrals/none), discovery mechanisms (well-known URI, robots Agentmap, HTML link, DNS), media types, and the formal schemas (CDDL / JSON Schema / OpenAPI) + conformance tooling.

• references/publishing.md — How to publish a catalog: building ai-catalog.json, hosting requirements (HTTPS, Content-Type, CORS), the .well-known path, DNS TXT/SRV alternatives, URN naming guidance per deployment context (enterprise / solo dev / local), the localhost anti-pattern, and validation commands.

• references/clients-and-connectors.md — How to build an ARD client (the 6-step discovery → verify → connect flow, with code) AND how to connect chatbots: Claude (plugin marketplace, remote MCP connector, legacy desktop config) and Gemini (Gems + CLI/API, MCP connector). Includes endpoints and the ~/.agentfinder/finders.json detail.

• references/ecosystem.md — The live reference implementations (GitHub Agent Finder, Hugging Face Discover, Cisco/AGNTCY AI Catalog) with exact endpoints; the contributors / governance picture; and how ARD relates to ai-catalog and the Agent Name Service (ANS) ("find with ARD, trust the name with ANS").

• references/glossary-and-faq.md — Every glossary term defined, plus the full FAQ (trust philosophy, context-window savings, malicious-tool concerns, central-directory question, ANS relationship). Read this for crisp definitions and the "why" answers.

• references/adrs-and-history.md — The Architecture Decision Records and version history: why /explore is a POST superset of a stats endpoint, search pagination, exclusion of EBNF from search, the shared query model, federation placement, URN pattern flexibility, the MCP media-type rename, and the ai→air NID change. Read when asked why a design choice was made or about version evolution.

• references/links.md — Every canonical URL: docs site pages, the GitHub repos, the spec/schema files, reference-implementation endpoints, and related standards. Read when the user wants source links or you need to point them to authoritative material.

Working with manifests and registries

When authoring a manifest, follow references/publishing.md and validate against the JSON Schema (npx ajv-cli validate -s ai-catalog.schema.json -d your-catalog.json) or the repo's conformance CLI (conformance/bin/conformance-test manifest <path|url>). When building a client or registry, follow references/clients-and-connectors.md and references/specification.md §Registry API. Prefer the repo schemas (spec/schemas/ai-catalog.schema.json, ard.cddl, ard.openapi.yaml) as the contract.