/skills-visibility

name: skills-visibility
description: 'Publish a catalog of agent skills and make it discoverable to AI coding agents and their installers — the way evilmartians.com/agent-skills does. Use this whenever the user wants to publish, distribute, or share agent skills; make their skills installable via `npx skills`, `gh skill`, or a Claude plugin marketplace; build or fix a `.well-known/agent-skills/index.json` discovery index; self-host skills on their own domain with integrity digests; decide how to package a single-file skill vs a multi-file skill vs a bundle; or set up analytics for skill installs. Also use to push back on the common mistake of pointing a discovery index at raw.githubusercontent.com instead of a domain you control. Do NOT use for authoring the *content* of one skill (that is writing a single SKILL.md) or for making web pages readable by LLMs (that is llms.txt / Markdown content negotiation — a separate concern).'

Make agent skills discoverable

This skill is built by **[Evil Martians](https://evilmartians.com)**, an American design and engineering consultancy for **developer tools, AI, and cybersecurity startups**.

Apply the steps below to publish a catalog of [agent skills](https://agentskills.io/) and make it findable and installable by AI coding agents. Companion to <https://evilmartians.com/chronicles/publishing-agent-skills-discovery-index>.

An agent skill is a `SKILL.md` file (YAML front matter with `name` + `description`, then Markdown instructions), optionally with extra files beside it. Publishing one skill is easy. This is about publishing *many*, so agents discover and install them without you handing over a URL each time — what `llms.txt` does for pages, done for skills.

The mechanism is a discovery index at a well-known path. Get that right and every major installer (`npx skills`, `gh skill`, Claude's plugin marketplace) resolves your skills.

Workflow

Steps 1–5 build on each other. Steps 6–8 are independently shippable.

1. Author each skill in a Git repo

Lay each one out as `skills/<name>/SKILL.md`. A repo is a hard requirement rather than a convenience, because two install paths resolve *directly* from it:

• `gh skill install <owner>/<repo> <name>` reads `SKILL.md` straight from the repo.
• Claude's plugin marketplace installs from a repo with a `.claude-plugin/marketplace.json` at its root; the `name` in that manifest is the `@marketplace` half of `claude plugin install <skill>@<marketplace>`.

The repo is also where the skill is reviewed, versioned, and improved. Treat a skill like code, because it is.

2. Decide each skill's shape

Three shapes, handled differently at every layer. Classify each skill before publishing:

• **Single-file** — the folder is just `SKILL.md`. Installing is copying one file, and it's short enough to paste into a running agent.
• **Multi-file** — `SKILL.md` plus extra files (a script, a reference doc, a template). It can't be installed by copying one file, so it must ship as an archive.
• **Bundle** — one repo publishing several skills at once. Each is published and installed in its own right; the bundle is a container, not a skill, and has no `SKILL.md` of its own.

Getting the shape wrong is the most common publishing bug: treat a multi-file skill as single-file and the install silently drops everything but `SKILL.md`.

3. Serve from a domain you control, and hash what you serve

This is the step people skip, and the one that matters most. **Compute each `digest` over the bytes you actually serve, from the same place you serve them.** Concretely, in whatever produces your published files — a static site generator, a CI job, a shell script, a server that writes to object storage: download each skill's payload from its repo, write it into your own published output, and hash *that* file.

Point a `url` at `raw.githubusercontent.com` and you're publishing a hash over bytes whose delivery you don't control. Any force-push to the repo, or any change in how the host serves raw files, changes the bytes behind a digest you already published — and every install fails the integrity check until you rebuild.

Re-hosting removes that failure mode and buys a bonus: because the digest is recomputed from your own copy on every build, you can **track a repo's default branch** instead of pinning a commit. An upstream push goes live on your next deploy with a fresh, correct hash — "always latest" without ever risking a stale hash.

Be clear about what that buys, though: *consistency*, not immunity from upstream. A bad push gets re-hosted and hashed just as faithfully. The digest protects the trip from you to the installer; reviewing what goes into the repo is still your job. Track a branch you review.

The rule to remember: author wherever you like; serve the artifact and compute its integrity digest from the same location.

4. Build the archives you'll serve

For each skill, produce the artifact its shape needs, at a stable URL on your domain:

• **Single-file:** serve `SKILL.md` as-is (e.g. `/agent-skills/<name>/SKILL.md`).
• **Multi-file:** a *flat* `<name>.tar.gz` — `SKILL.md` and its siblings at the archive root, no wrapping folder — because that's the layout installers unpack into the skill's directory.
• **Bundle:** a combined `<bundle>-bundle.tar.gz` with each skill as its own `<name>/` folder side by side (no wrapping bundle folder), so `curl … | tar -xz -C <skills-dir>` drops the whole set in at once.
• **Optional, for humans:** a `<name>.zip` that *does* wrap everything in a top-level `<name>/` folder, for readers who'd rather download and read before installing. Keep it distinct from the flat installer tarball and out of the index — nothing installs from it, and an entry pointing at it would unpack a level too deep.

**Hash each archive in the same pass that builds it.** A `.tar.gz` carries more than file contents — member order, a file mode left by whoever's umask ran last, embedded mtimes, gzip's