Your skill probably is indexed. It just cannot be installed.

The scale, honestly stated

The numbers are startling and worth stating carefully. The vercel-labs/skills repo was created on 14 January 2026 and sits around 29,400 stars. Downloads of the skills npm package went from 240,000 in January to 44.4 million in July. The skills.sh homepage advertises over 1.29 million indexed skills, though the page payload also carries a much smaller totalSkills figure, so treat the headline number as a claim rather than a count. The bundled find-skills skill, which instructs agents to consult the leaderboard before recommending anything, has over 3 million installs on its own.

Against that: 1,090 open issues, of which 191 are titled "request indexing" — three filed on 21 August alone. There is no submission form, so when discovery fails silently, a GitHub issue is the only lever people can find. Most of those issues will never need answering, because the fix is on the skill author's side.

Failure one: the YAML that looked fine

Our skill was listed, showed an install count, and had been recommended in our own docs for weeks. Then we watched an actual install:

⚠ Skipped SKILL.md — YAML parse error: Nested mappings are not
  allowed in compact mappings

description: Share an HTML page privately with someone outside the chat: a clie…
                                                                        ^

One unquoted colon inside the description. YAML reads everything after it as a nested mapping, the frontmatter fails to parse, and the installer skips the file. The listing page kept rendering; the install delivered nothing. Every SKILL.md we had ever copied that description into carried the same fault — including one pinned into a marketplace submission. The fix is a pair of quotes.

Failure two: the shadowed directory

The same repo held seven skills: one at the root, six under skills/<name>/. Every install reported Found 1 skill — the root one. The six others did not exist as far as the CLI was concerned, and no search would ever surface them.

Moving the root SKILL.md into skills/publish/ — changing nothing else — flipped the same command to Found 7 skills. A root SKILL.md shadows the directory. The indexed multi-skill repos all share the same shape: everything under skills/, nothing at the root. Issue #1716 documents the wider class, where a recognised path prefix silently swallows files in unrecognised locations, and has sat open with zero comments since July.

How ranking and search actually work

Installs are the ranking signal, counted via CLI telemetry (opt out with SKILLS_NO_TELEMETRY=1), across all-time, trending, and hot windows. Search matches name and description text. That has a consequence authors consistently miss: a description written in product language is invisible to the queries people actually type. Ours surfaced for its own brand name and for nothing else — not "publish html", not "share a page privately" — while a 59-install skill outranked it on our own use case, purely on wording. The index is server-side and recrawls on its own schedule; a description edit takes days to show, so fix wording before chasing installs.

The checklist

In order, because each failure hides the ones behind it:

• Run npx skills add you/your-repo@your-skill yourself and read every line. The installer reports what it skipped nowhere else.
• Quote any frontmatter description containing a colon. Validate the YAML if in doubt.
• Multi-skill repo: everything under skills/<name>/SKILL.md, no root SKILL.md.
• Dedicated repo beats a corner of a monorepo — issue #1469 documents skills add pulling 1,831 files from one.
• Write the description in the words of the job, not the product. It is the entire search surface.
• Then wait out the recrawl before concluding anything.

What changed this month

Two updates worth knowing while you are in there. Skill Packs shipped on 7 August: bundle skills from folders, zips, or repos into one shareable URL with one-command install — with no versioning, checksums, or signatures yet, which others have rightly flagged as a supply-chain gap. And v1.5.23, released 18 August, stopped the CLI extracting your stored GitHub CLI token via gh auth token and stopped sending private repo identifiers to telemetry endpoints — a quiet fix to a long-standing pair of issues that is worth an upgrade on its own.

Disclosure of the receipts: the skill in these war stories is ours — stacktree-publish, which publishes HTML from any agent to a private link on Stacktree. Both failures above are reproduced from its commit history, not reconstructed from memory.