ard-registry-builder

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/validate_catalog.py <path-or-url> [--json] [--strict]	Validate a manifest: JSON Schema plus ARD semantic rules. Exit 1 on errors.
scripts/test_registry.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	JSON Schema for the ai-catalog.json manifest format (Draft 2020-12), bundled for offline validation.
assets/ard-entry.schema.json	JSON Schema for a standalone ARD entry and ArdManifest (the v0.91 ard.json format). Use this to validate entries individually or a bare-entries manifest.
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 ./ard.json. (Without scaffolding, copy a file from assets/templates/.)
2. For each resource, set identifier (urn:air:<publisher>:<namespace?>:<name>), displayName, type (the artifact's media type), and exactly one of url or data.
3. Add description, tags, capabilities, and especially representativeQueries (2–5 natural-language queries) — the single biggest lever for being found by semantic search. Absence is a conformance warning in v0.91; presence is still strongly recommended.
4. Add trustManifest only when you have real identity/attestations; keep simple entries lean.
5. 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.
6. Validate: python scripts/validate_catalog.py ./ard.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>.
2. 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.
3. 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.
4. 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).
2. Required checks failing → the server is not ARD-conformant on the mandated floor (/search). Fix the envelope/status against references/registry-api.md.
3. 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.
2. Bump the entry's version and refresh updatedAt (ISO 8601) when the artifact changes.
3. Adding a resource → append an entry; ensure its identifier is unique (the validator flags duplicates).
4. 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, JSON-LD context extension, 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 (ard.json), 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.