Skip to content

SKILL.md

Latest commit

 

History

History
236 lines (172 loc) · 8.87 KB

SKILL.md

File metadata and controls

236 lines (172 loc) · 8.87 KB
Raw
name ai-catalog-cli
description Use this skill whenever the user wants to discover, inspect, validate, or install AI resources — MCP servers, A2A agents, agent skills, or other AI artifacts — from an AI Catalog. Triggers include requests to find an MCP server, register an MCP server with the agent, install an agent skill, find or connect to an A2A agent, browse available AI tools, search a catalog, validate a catalog document, or work with OCI-packaged catalogs.
license Apache-2.0
compatibility Requires the `ai-catalog` binary on PATH. Install with `cargo install ai-catalog-cli`.
metadata
author version
ai-catalog-cli
0.1

AI Catalog CLI

ai-catalog is a command-line tool for discovering, validating, and pulling resources from AI Catalogs — typed JSON documents (application/ai-catalog+json) that index MCP servers, A2A agents, agent skills, and other AI artifacts.

Core concepts

  • Catalog — a remote JSON file (application/ai-catalog+json) that lists typed entries. Catalogs can nest other catalogs (fetched up to 4 levels deep).
  • Entry — a single item in a catalog with an identifier (URN), a type (MIME type), and a url pointing to the artifact.
  • Registry — the local list of catalogs registered via catalog add or oci add, stored at ~/.ai-catalog/.

Common entry types:

Type Artifact
application/mcp-server-card+json MCP server card
application/a2a-agent-card+json A2A agent card
application/agent-skills+md Agent skill (markdown)
application/ai-catalog+json Nested catalog

Workflow

1. Register a catalog

Before searching, register at least one catalog:

ai-catalog catalog add <name> <url>

Example:

ai-catalog catalog add ai-tools https://raw.githubusercontent.com/Agent-Card/ai-catalog-cli/main/fixtures/spec-example.json

Accepts HTTP/HTTPS URLs or file:// paths. Nested catalogs are fetched and cached automatically.

2. Search for entries

ai-catalog search <keyword>             # full-text search across all registered catalogs
ai-catalog search <keyword> -n 100      # override result limit (default 50)
ai-catalog search <pattern> --regex     # treat keyword as a regular expression
ai-catalog search <keyword> --json      # machine-readable output

Searches identifier, displayName, description, and tags. Works fully offline after the catalog is cached.

3. Inspect an entry

ai-catalog show <identifier>                              # table view
ai-catalog show <identifier> --json                       # full entry JSON
ai-catalog show <identifier> --scope <catalog-name>       # scope to a registered catalog by name
ai-catalog show <identifier> --scope <url>                # scope to any catalog by URI (file:// or http/https)
ai-catalog show <identifier> --media-type <mime>          # filter/disambiguate by MIME type

--scope accepts either a registered catalog name or a URI directly. file:// URIs are read from disk; http:///https:// URIs are fetched and cached on the fly without registering.

--media-type on a catalog entry resolves its children and shows the single entry matching that type; None or application/ai-catalog+json shows the catalog entry itself.

4. Pull an artifact

ai-catalog pull <identifier>                                 # write to current directory
ai-catalog pull <identifier> -o <dir>                        # write to a specific directory
ai-catalog pull <identifier> -o -                            # stream artifact bytes to stdout
ai-catalog pull <identifier> --scope <catalog-name-or-url>   # narrow search to one catalog
ai-catalog pull <identifier> --media-type <mime>             # required when <id> is a catalog entry

Important: if <identifier> resolves to a catalog entry (type application/ai-catalog+json), pull requires --media-type:

--media-type value Result
application/ai-catalog+json Write the catalog JSON document itself
<other> e.g. application/json Pull the single child entry of that type (error if 0 or >1 match)
(omitted) Error — suggests using --media-type

--scope obeys the same URI rules as show (name or URI).

Common workflows

Install an MCP server into your agent

MCP server cards (application/mcp-server-card+json) contain a remotes array with endpoint URLs:

# Find the server
ai-catalog search <keyword>

# Stream the card through jq to get the remote URL
MCP_URL=$(ai-catalog pull <identifier> -o - | jq -r '.remotes[0].url')

Register that URL using the mechanism of the host you are running in. Claude Code provides a CLI for it:

claude mcp add --transport http <name> "$MCP_URL"

Other hosts, including Cursor, VS Code, and Codex, register MCP servers through their own command or configuration file. Use the host's documented mechanism rather than assuming a claude binary is on PATH.

Install an agent skill

Agent skills (application/agent-skills+md) are markdown files following the Agent Skills standard. A skill must live in a directory named after it, with the markdown as SKILL.md inside, so create the directory before pulling:

NAME=<skill-name>
mkdir -p ~/.agents/skills/"$NAME"
ai-catalog pull <identifier> -o ~/.agents/skills/"$NAME"/SKILL.md

To install all skills matching a search:

ai-catalog search skill --json \
  | jq -r '.entries[].identifier' \
  | while read -r id; do
      name=${id##*:}
      mkdir -p ~/.agents/skills/"$name"
      ai-catalog pull "$id" -o ~/.agents/skills/"$name"/SKILL.md
    done

~/.agents/skills/ is the cross-host location read by Cursor, Copilot, VS Code, Codex, and Gemini CLI. Claude Code reads ~/.claude/skills/, which several other hosts also honour. Substitute the directory your host scans.

Connect to an A2A agent

A2A agent cards (application/a2a-agent-card+json) contain supportedInterfaces with the endpoint and protocol binding:

# Pull the agent card
ai-catalog pull <identifier> -o ./

# Extract endpoint and binding
AGENT_URL=$(jq -r '.supportedInterfaces[0].url'             ./agent.json)
BINDING=$(jq -r   '.supportedInterfaces[0].protocolBinding' ./agent.json)

# Send a message
a2acli --base-url "$AGENT_URL" --binding "$BINDING" send "<message>"

# Retrieve the result
a2acli --base-url "$AGENT_URL" --binding "$BINDING" get-task <task-id>

Catalog management

ai-catalog catalog list                  # list registered catalogs (--json supported)
ai-catalog catalog update <name>         # re-fetch from source, skip if unchanged
ai-catalog catalog remove <name-or-url>  # remove and garbage-collect cached objects

Validation and formatting

ai-catalog validate <path|->             # validate catalog JSON against the spec
ai-catalog validate --json <path|->      # machine-readable validation result
ai-catalog format <path|->               # pretty-print a catalog document

Validation reports conformance level (minimal, discoverable, or trusted) and any errors or warnings. Exit code 0 = valid, 1 = invalid.

OCI workflows

Use oci subcommands to work with OCI-packaged catalogs (e.g. from GHCR):

# Pack a catalog JSON into an OCI artifact envelope
ai-catalog oci pack <path|->

# Push a catalog to an OCI registry (requires `oras` on PATH)
ai-catalog oci push <path|-> <registry-target>
  # e.g. ai-catalog oci push catalog.json ghcr.io/example/ai-catalog:latest
  # --plain-http       use HTTP instead of HTTPS
  # --insecure         skip TLS verification
  # --cosign-key <key> sign trust manifests

# Export a catalog to an OCI image layout directory
ai-catalog oci export-layout <path|-> <layout-dir>
  # --tag <tag>  (default: latest)

# Import an OCI image layout into the local registry
ai-catalog oci add <name> <layout-dir>

# Search, inspect, and pull from OCI-sourced catalogs only
ai-catalog oci search <keyword>
ai-catalog oci show <identifier> [--media-type <mime>]
ai-catalog oci pull <identifier> -o <dir> [--media-type <mime>]

Trust inspection

ai-catalog trust inspect <path|->        # show trust report (identity, signatures, attestations)
ai-catalog trust inspect --json <path|-> # machine-readable report

Exit code 0 = clean, 1 = errors found (identity mismatch, malformed signature, weak digest).

Environment variables

Variable Description Default
AI_CATALOG_CACHE_DIR Override default cache directory ~/.ai-catalog/
AI_CATALOG_COSIGN_BIN Path to cosign binary cosign
AI_CATALOG_ORAS_BIN Path to oras binary oras
COSIGN_PASSWORD Password for encrypted Cosign private key (none)

Exit codes

Code Meaning
0 Success
1 Validation/trust errors, parse failures, runtime errors
2 Usage errors (missing arguments, unknown options)