A detailed how-to for publishing 'agent skills'—SKILL.md files that teach AI coding agents repeatable practices—so agents like Claude, Cursor, Codex, and Gemini CLI can discover and install them. Covers publishing a .well-known/agent-skills/index.json discovery index (built on a Cloudflare RFC and the agentskills.io schema), SHA-256 integrity digests, the three skill shapes (single-file, multi-file archive, and bundle), why to author on GitHub but re-host payloads on your own domain for digest consistency, and the four install paths (npx skills, claude plugin, gh skill, curl). Uses Evil Martians' own open-sourced skill catalog as the worked example, plus a checklist for verifying a catalog before shipping and notes on instrumenting install analytics.
Table of contents
Other parts:What’s an agent skill, and why open-source ours?The discovery index: one JSON file agents already look forMaking your site visible to LLMs: 6 techniques that work, 8 that don'tSingle-file, multi-file, and bundle: three shapes, three install pathsAuthor in a repo, serve from your own domainEvery install method, and why we shipped all of themFour checks before you ship yoursMeasuring what gets installedWhich AI actually reads your site? Two months of LLM traffic, measuredFAQQuestions this post answers
What is the .well-known/agent-skills/index.json discovery format and who defined it?
It is a JSON discovery document published at a domain's .well-known/agent-skills/ path, listing each agent skill's name, description, type, url, and sha256 digest. The format comes from an open RFC authored by Cloudflare, building on RFC 8615 (the same convention behind robots.txt and security.txt), and points at the schemas.agentskills.io/discovery/0.2.0 schema. Anthropic separately defined the underlying SKILL.md skill format. Developers wiring up agent-discoverable tooling can follow discovery-format changes like this on daily.dev.
How do I make my AI agent skills installable via npx skills?
Publish a .well-known/agent-skills/index.json at your domain listing each skill's name, description, type (skill-md or archive), url, and sha256 digest, then run npx skills add https://yourdomain.com/agent-skills --skill <name>. The full https:// URL is required to trigger discovery mode; a bare owner/repo or domain is instead treated as a Git repo to clone. The installer re-verifies the digest before writing anything to disk. daily.dev helps developers deciding how to distribute agent skills track install tooling like this.
Why should I re-host agent skill files on my own domain instead of pointing to raw GitHub URLs?
Because a raw GitHub URL tracking a branch will change bytes underneath an already-published digest, causing every conformant installer to refuse the skill once verification fails. Re-hosting on your own domain means the fetch, write, and hash all happen in the same build, so the digest always matches exactly what is served, at the cost of a small deploy-latency delay versus instant GitHub updates. Teams shipping installable packages can weigh integrity trade-offs like this via daily.dev.