| name | agntcy-dir |
| description | Use this skill to interact with an AGNTCY Directory (DIR) instance. DIR is a distributed peer-to-peer registry of AI agent records described in OASF. Use it to publish (push), discover (search), retrieve (pull), sign, and verify agent records. |
| metadata | {"author":"AGNTCY Contributors","version":"1.0.0"} |
AGNTCY Directory (DIR)
DIR is a distributed registry for AI agent records. Records describe agents using
the Open Agentic Schema Framework (OASF) and
are content-addressed by CID.
This skill explains how to talk to a running DIR node. You can use the MCP server,
the dirctl CLI, the language SDKs, or the raw gRPC API — pick whichever channel
your environment supports.
Vocabulary
- Record — an OASF JSON document describing one agent (name, version, skills, locators, modules, signatures).
- CID — Content Identifier; the SHA-based hash that uniquely names a record. Pushing the same record twice yields the same CID.
- Skill / Domain — OASF taxonomy nodes describing what an agent does (e.g.
natural_language_processing/text_completion) and where it operates.
- Module — typed extension on a record (e.g.
core/language_model/agentskills, integration/mcp, integration/a2a).
- Locator — pointer to a runnable artifact for the agent (
container_image, source_code, helm_chart, package, binary, url).
Channels
| Operation | MCP tool | CLI | Go SDK |
|---|
| Push a record | agntcy_dir_push_record | dirctl push <file> | client.Push |
| Pull by CID | agntcy_dir_pull_record | dirctl pull <cid> | client.Pull |
| Search local | agntcy_dir_search_local | dirctl search | client.Search |
| Validate against OASF | agntcy_oasf_validate_record | dirctl validate <file> | — |
| List OASF versions | agntcy_oasf_list_versions | — | — |
| Sign a record | — | dirctl sign --key=<cosign.key> <cid> | client.Sign |
| Verify a signature | agntcy_dir_verify_record | dirctl verify <cid> | client.Verify |
| Verify name ownership | agntcy_dir_verify_name | dirctl naming verify <cid> | — |
| Import MCP / A2A / SKILL.md | agntcy_oasf_import_record | dirctl import --type=<mcp|a2a|agent-skill> | — |
Workflow: publish an agent record
- Author or generate an OASF record JSON. Required top-level fields for the
1.0.0 schema:
name, schema_version, version, description, authors,
created_at (RFC3339), skills. Optional: domains, locators, modules,
annotations.
- Validate against the OASF schema before pushing — the server rejects
malformed records with
InvalidArgument.
- Push. The server returns the CID. Pushes are idempotent: pushing the same
bytes a second time returns the same CID without creating a duplicate.
- Optionally sign the record with cosign — produces a signature referrer
linked to the CID. Anyone can later verify signature and name ownership.
dirctl validate agent.json
CID=$(dirctl push agent.json --output=raw)
dirctl sign --key=cosign.key "$CID"
Workflow: discover and pull a record
- Search by structured filters (names, versions, skills, locators, authors, …).
Filters use wildcards:
* (any), ? (one char), [abc] (set).
- The search returns CIDs. Pull each CID to get the full record JSON.
dirctl search --skill-name "*text_completion*" --limit 20
dirctl pull <cid>
For natural-language searches via an LLM, prefer the search_records MCP prompt,
which translates a free-text query into structured filters automatically.
OASF essentials
- Schema versions in active use:
0.7.0, 0.8.0, 1.0.0. Pick the latest your
tooling supports; 1.0.0 is the current default.
- Module enum is closed in 1.0.0 — only these
names validate:
language_model, prompt, core/language_model/agentskills, evaluation,
observability, a2a, acp, agentspec, mcp. Custom payloads belong in
the top-level annotations map.
- Skills and domains are taxonomies; resolve
id ↔ name with the
agntcy_oasf_get_schema_skills and agntcy_oasf_get_schema_domains MCP tools
(or fetch the schema JSON directly).
Common pitfalls
- A record's CID covers its bytes — any change (whitespace, key order) yields a
new CID. Re-push only when the record actually changes.
- Names beginning with
http:// or https:// opt into domain-based name
ownership verification (/.well-known/jwks.json on the host). Plain names
skip that path.
- Search defaults to local-only. To find records on remote peers, use routing
search (
dirctl routing search … / client.SearchRouting).
- The server caps records at 4 MB and metadata at 100 KB. Keep large blobs in
external storage and reference them via locators.
Pointers
