AGNTCY Directory (dirctl)

The AGNTCY Directory (DIR) is a distributed, peer-to-peer registry of AI agent records described in OASF. Records are content-addressed by CID and carry skills, domains, modules (MCP, A2A, Agent Skills), locators, signatures, and security scan results.

This skill turns natural-language requests into dirctl workflows. It is a router: read the matching reference file below before acting on a workflow. Read more than one when the request spans workflows (e.g. "import and publish" → authoring + publishing).

Dispatch

Vocabulary

• Record — one OASF JSON document describing an agent (name, version, skills, domains, locators, modules, annotations).
• CID — content identifier; hash of the record bytes. Same bytes → same CID. Any change → new CID.
• Reference — how commands address records: <cid>, <name>, <name>:<version>, <name>@<cid>, <name>:<version>@<cid> (the @<cid> forms are hash-verified and fail on mismatch).
• Skill / Domain — OASF taxonomy nodes describing what an agent does and where.
• Module — typed payload on a record: integration/mcp (MCP server), integration/a2a (A2A card), core/language_model/agentskills (Agent Skill).
• Locator — pointer to a runnable artifact (container_image, source_code, helm_chart, binary, …; each with a urls list).
• Referrer — Artifact attached to a record: signature, public key, security scan report, identity claim.
• Subject / Claim — a subject is who a record says it belongs to (dns:example.com, did:web:…, spiffe://…, ans://…), declared in the agntcy.dir/owner / agntcy.dir/identity annotations. A claim is a signature by that subject's key; the reconciler re-verifies it against the subject's published keys on every run. Record names are not verified — claims are.
• Content policy — a node operator's CEL/OPA rule; records failing an enforced policy are withheld by that node only.

Prerequisites

dirctl must be on PATH — probe with dirctl version (works in every shell; POSIX: command -v dirctl, PowerShell: Get-Command dirctl). If missing, follow the install section of references/setup.md — never suggest building from source.

A reachable Directory server is required for everything except context, validate, version, and the local-state install commands (install agents, install list, install pin, install unpin, install prune, uninstall). Default is localhost:8888 (local daemon). Server selection order: --context <name> flag → DIRECTORY_CLIENT_CONTEXT → current_context in config → --server-addr / DIRECTORY_CLIENT_SERVER_ADDRESS overrides.

CLI conventions (apply everywhere)

• Parse, don't scrape: request -o json (or -o jsonl for streams) when you need to read results; -o raw for CIDs in shell pipelines. Structured formats write data to stdout and messages to stderr, so piping to jq is safe. validate, context, auth, daemon, and version do not take -o.
• Quote every argument — record names contain / and :.
• Capability probing: command surface varies by version. Before relying on newer commands (install, init, NL search), check dirctl <cmd> --help; if absent, use the documented fallback in the relevant reference file.
• Auth: never invent auth flags. On an auth error, surface the raw error and ask the user how to authenticate (see setup reference: auth login, --auth-mode, --auth-token).
• Authentication is not authorization: a valid token from auth status says nothing about what the user may do. Gateways enforce per-method access control, so PermissionDenied / Forbidden on push, sign, routing publish, delete, or sync is an entitlement problem — logging in again cannot fix it. Name the denied method, say it needs elevated rights on that deployment, and stop; only Unauthenticated and expired-token errors are login problems.
• Destructive ops (delete, uninstall, sync delete, --force, a reconciler prune job with dry_run: false, switching a content policy to enforce): always confirm with the user first.
• Never fabricate CIDs, names, versions, scores, or scan results — every value shown must come from real command output.

Platforms & shells

dirctl ships for Linux and macOS (amd64 + arm64) and Windows (amd64 only — no windows-arm64 build; the binary is dirctl.exe). Homebrew covers macOS/Linux only; on Windows install from GitHub Releases (see setup reference). dirctl behaves identically everywhere — only the wrapping shell syntax and paths differ.

Emit commands for the shell the host actually runs — never assume bash. Code blocks in this skill are written for POSIX shells (bash/zsh) and run as-is on Linux/macOS. On Windows (PowerShell), translate before running:

Path rules: ~ in this skill means the user's home directory — %USERPROFILE% on Windows (e.g. ~/.agntcy/dir/ → %USERPROFILE%\.agntcy\dir\). When unsure where the effective client config lives, run dirctl context show instead of guessing paths.

Environment adaptivity

Maximize the host's native capabilities; degrade gracefully:

Other agentic hosts (Cursor, Windsurf, Zed, Cline, Roo, Gemini CLI, opencode, Continue, Codex, …) are not listed per-column — detect capabilities instead of matching product names: if an interactive question tool exists, use it; otherwise behave like the CLI column. You generally know which host you are running in; when you don't, infer it from your available tools, not from guesses.

Rules:

• Use an interactive question tool whenever one exists for: picking records to install, choosing install scope/agents, and confirming destructive actions. Only fall back to free-text prompts when no such tool is available.
• Never promise webviews, side panels, or native dialogs — chat surfaces render Markdown only.
• Long operations (init downloads ~89 MB; imports and syncs can run minutes): warn the user before starting and report progress from command output.
• When the user's host is itself an install target (e.g. VS Code → vscode, Claude Code → claude-code, Cursor → cursor), default installs to that host's agent ID (see install reference).
• Headless / CI runs (no human available to answer): never block on interactive prompts. Use --yes for init and install, authenticate via DIRECTORY_CLIENT_AUTH_TOKEN or auth login --device / --no-browser, and when a decision genuinely requires a human, fail fast with a clear message instead of waiting.

Pointers

• CLI reference: https://dir.agntcy.org/latest/dir/dir-cli-reference/
• Quickstart: https://dir.agntcy.org/latest/dir/dir-quickstart/
• OASF schema: https://schema.oasf.outshift.com
• Repo: https://github.com/agntcy/dir