ARD Registry Builder

Agentic Resource Discovery (ARD) lets AI clients discover agents, MCP servers, skills, and APIs at runtime by search instead of hardcoding them. Publishers describe their resources in a static ai-catalog.json capability manifest; dynamic Agent Registries index those manifests and answer POST /search. This skill helps you engineer both — author, validate, test, and maintain them so they actually pass conformance and get discovered.

Two artifacts, one mental model — identity vs location:

• The manifest (ai-catalog.json, static) lists entries. Each entry's identifier is a

permanent urn:air: URN (identity); its url/data is the movable endpoint (location).

• The registry (REST API, dynamic) is a service that searches indexed entries.

Never bake a hostname into a URN; never treat a URL as an identity. Almost every ARD mistake traces back to confusing these two.

Bundled tools (use these — don't reinvent them)

All scripts are stdlib-only Python 3.8+; validate_catalog.py uses the jsonschema library when present (recommended: pip install jsonschema) and falls back to a built-in checker.

| Tool | Purpose | | :-- | :-- | | scripts/validatecatalog.py <path-or-url> [--json] [--strict] | Validate a manifest: JSON Schema plus ARD semantic rules. Exit 1 on errors. | | scripts/testregistry.py <base-url> [--query T] [--json] | Probe a live registry's /search (required), /agents, /explore for conformance. | | scripts/new_catalog.py --template minimal\|enterprise\|local-dev [--publisher D] [--host N] --out F | Scaffold a starter manifest. | | assets/ai-catalog.schema.json | The authoritative JSON Schema (Draft 2020-12), bundled for offline validation. | | assets/templates/*.json | Valid starting points: minimal, enterprise (trust + registry entry), local-dev. |

Always validate after every edit, and validate the live URL after publishing — not just the local file.

Decide what the user needs

• "Create / scaffold / start a catalog" → Workflow 1.
• "Validate / check / is this valid / why won't it pass conformance / fix this manifest" →

Workflow 2 (run validate_catalog.py first, before reading anything).

• "Test / probe my registry / does my /search work / is my API ARD-compliant" → Workflow 3.
• "Add an agent / bump a version / change an endpoint / maintain" → Workflow 4.
• "How does X work" (data model, API, trust, publishing) → read the matching reference below.

Workflow 1 — Build a manifest

1. Pick the closest template and scaffold it:

python scripts/new_catalog.py --template enterprise --publisher mycorp.com --host "MyCorp AI" --out ./ai-catalog.json. (Without scaffolding, copy a file from assets/templates/.)

1. For each resource, set identifier (urn:air:<publisher>:<namespace?>:<name>),

displayName, type (the artifact's media type), and exactly one of url or data.

1. Add description, tags, capabilities, and especially representativeQueries (2–5) —

the single biggest lever for being found by semantic search.

1. Add trustManifest only when you have real identity/attestations; keep simple entries lean.
2. Choose the publisher domain to match the deployment context (enterprise FQDN, public

namespace like github.com:you, or agent.localhost/example.com for local-only). See references/data-model.md.

1. Validate: python scripts/validate_catalog.py ./ai-catalog.json. Fix until it passes.

Workflow 2 — Validate / debug a manifest

1. Run the validator first, before reading the file by hand — it pinpoints issues fast:

python scripts/validate_catalog.py <path-or-url>.

1. Read findings by severity. ERROR must be fixed; WARN should be (use --strict in CI

to enforce); INFO is advice. Every finding names a JSON path and a stable code.

1. Map the code to a fix using references/validation-rules.md. The high-frequency ones:

- urn-wrong-nid → change urn:ai: to urn:air:. - value-or-reference → keep exactly one of url / data. - schema (oneOf/required/pattern/minItems) → fix the structure the message names. - urn-localhost / urn-publisher-fqdn → use a verifiable or reserved-placeholder domain. - trust-domain-mismatch → make the trustManifest.identity domain match the URN publisher.

1. Re-run until clean. For CI, use --json (machine output) and/or --strict (fail on warnings).

Workflow 3 — Test a live registry API

1. Probe it: python scripts/test_registry.py https://registry.example.com/api/v1.

The tester sends a real POST /search, validates the results envelope (each item is a catalog entry carrying a score 0–100 and a source), confirms a malformed request is rejected with 400 + errorCode + message, and checks optional /agents and /explore (skipped, not failed, when a server returns 404/501).

1. Required checks failing → the server is not ARD-conformant on the mandated floor (/search).

Fix the envelope/status against references/registry-api.md.

1. For exploratory calls, hit endpoints directly with curl (see references/registry-api.md).

Workflow 4 — Update / maintain

1. Edit the entry. Keep the identifier URN stable — it is a permanent contract. To move an

endpoint, change url (or data), never the URN.

1. Bump the entry's version and refresh updatedAt (ISO 8601) when the artifact changes.
2. Adding a resource → append an entry; ensure its identifier is unique (the validator flags

duplicates).

1. Re-validate the file; if it is already published, also validate the live URL and re-probe any

registry. Treat "passes validation" as the definition of done.

Golden rules (the why behind the checks)

• URN = identity, url/data = location. Stable URNs keep search indexes, client references,

and orchestration working while infrastructure moves underneath them.

• The publisher segment must be a verifiable FQDN. Registries extract it and bind it to

trustManifest.identity to stop namespace squatting. localhost and bare words break this.

• Exactly one of url or data. Predictable parsing in enterprise pipelines depends on it.
• score is relevance, not trust. Never gate safety on a search score; verify

trustManifest independently.

• Validate early, validate often, validate the live URL. Most "it won't index" problems are

schema or hosting issues a 1-second validator run would have caught.

Reference files

Read the one matching the task; each has a table of contents.

• references/data-model.md — manifest/entry fields, URN format, media types, value-or-reference,

trust manifest, and the known urn:air: vs urn:ai: doc inconsistencies.

• references/registry-api.md — /search, /explore, /agents, the query/filter model,

federation modes, and error codes.

• references/validation-rules.md — every check the validator runs, with its code and severity.
• references/publishing.md — well-known URI, CORS, DNS discovery, and public reference

registries to test against.

Evals

evals/evals.json holds realistic task prompts for the skill-creator evaluation loop. Use it to benchmark or regression-test changes to this skill.