hf-discover

// Overview

hf-discover is Hugging Face's implementation of Agentic Resource Discovery (ARD), the open specification for how an agent looks up the resources it needs — Skills, MCP servers and other endpoints — instead of having them hard-wired at configuration time. The repository ships both halves: a client you run as a `hf` CLI extension, and a server that exposes an ARD catalog over HTTP.

It works in two modes. Search queries a single catalog directly, running semantic search over indexed Skills and Hugging Face Spaces. Navigate does federated discovery: it fetches `/.well-known/ai-catalog.json` from a site, follows the registries that document links to within a depth limit, and merges the ranked results. That is the part that makes discovery decentralised — any site can publish a catalog and be found without registering anywhere central.

The server side implements the ARD v0.5 envelope: `POST /search` returns catalog entries typed by media type (`application/ai-skill`, `application/mcp-server-card+json`, `application/vnd.huggingface.space+json`), with domain-anchored `urn:air:` identifiers, alongside endpoints that serve a Space's `SKILL.md` or MCP `server.json`. A hosted instance runs as a Hugging Face Space from a reproducible Docker definition. The project is MIT-licensed and needs Python 3.10 or newer.

// What it does

• Client and server for the Agentic Resource Discovery v0.5 specification
• Search mode: semantic search over one catalog of Skills and Hugging Face Spaces
• Navigate mode: federated discovery that follows `/.well-known/ai-catalog.json` across registries with a depth limit
• Typed catalog entries for AI Skills, MCP server cards and Space descriptors, with `urn:air:` identifiers
• Installs as an extension of the `hf` CLI, or runs standalone as `hf-discover`
• Ships a Docker Space definition for hosting your own catalog endpoint

// Getting started

The recommended install adds hf-discover as an extension to the Hugging Face CLI, which then exposes the `hf discover` subcommand.

uv tool install -U huggingface_hub
hf extensions install huggingface/hf-discover
hf discover --version

hf discover search "generate image" --limit 5
hf discover search "transcribe some audio" --kind mcp --json
hf discover search --registry-url https://registry.example "generate image"

hf discover navigate "segment hockey players in an image"
hf discover navigate https://huggingface.co "help me set up an RL environment"
hf discover serve --port 8080

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Let an agent look up a Skill or MCP server mid-task instead of shipping a fixed tool list
• Publish your own site's tools as an ARD catalog that other agents can find
• Run a private registry of internal Skills and MCP servers behind the same API
• Explore what a domain exposes to agents before wiring anything up

// How hf-discover compares

hf-discover alongside other open-source agent skills & plugins tools AI/TLDR tracks, ranked by GitHub stars.