# skills.sh indexing explained: why your skill is not listed, and what actually breaks · Stacktree Source: https://stacktr.ee/blog/skills-sh-indexing-explained [Skip to content](#main) [Stacktree](/)[Developers](/developers)[Agents](/agents)[Docs](/docs)[Use cases](/use-cases)[Pricing](/pricing)[Blog](/blog)[Dashboard](https://app.stacktr.ee)[Sign in →](https://app.stacktr.ee) By [ Steve Smith ](/about) · Founder, Stacktree · Last updated August 22, 2026 blog · hands-on · receipts included # Your skill probably is indexed. It just cannot be installed. The agent-skills index has no submission form, no error messages, and 191 open GitHub issues from people asking to be listed. We shipped a listed skill, discovered it had been broken on install the whole time, then found a second failure hiding five more skills. Here is what the index actually does, and the checklist we wish had existed. [ Get started free ](https://app.stacktr.ee/?join=1&from=seo_blog_skills_sh_indexing_explained) install npx stacktree-install Copy No card · 3 pages free · about a minute ## Why is my skill not showing up on skills.sh? Almost always one of three silent failures, not a missing submission: a YAML parse error in the SKILL.md frontmatter (an unquoted colon is enough), a root SKILL.md shadowing the skills/ directory so only one skill enumerates, or the custom-layout path bug tracked in vercel-labs/skills issue #1716. The installer and the index skip what they cannot parse without telling anyone, so the failure looks like absence. ## On this page - 01 [ The scale, honestly stated ](#scale) - 02 [ Failure one: the YAML that looked fine ](#yaml) - 03 [ Failure two: the shadowed directory ](#shadow) - 04 [ How ranking and search actually work ](#ranking) - 05 [ The checklist ](#checklist) - 06 [ What changed this month ](#august) ## 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//`. 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//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](https://skills.sh/stevysmith/stacktree-skill/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. See it in one call, no account ``` `curl -X POST https://api.stacktr.ee/sites -F file=@index.html # → a private URL, live for 24h. Claim it free to keep it.` ``` If your agents emit HTML, they need a durable publish target: publish once, then `update_site` on every revision keeps the same URL forever. MCP, REST, and skills all speak it: the map is at [agent.txt](https://stacktr.ee/agent.txt). [ Get an API key free ](https://app.stacktr.ee/?join=1&from=bridge_blog_skills_sh_indexing_explained) FAQ ## Frequent questions What is skills.sh? + The leaderboard and search index for agent skills installed by the npx skills CLI (the vercel-labs/skills project, roughly 29,000 GitHub stars). Skills install straight from GitHub repos with npx skills add owner/repo@skill; skills.sh indexes them, counts installs via the CLI's telemetry, and ranks all-time, trending, and hot. Its bundled find-skills skill tells agents to check the leaderboard before recommending anything, which is what makes placement matter. Do I need to submit my skill to skills.sh? + No. There is no submission form; the index discovers skills from public GitHub repos. That is also why 191 open issues on the repo are titled "request indexing": when discovery silently fails, filing an issue is the only lever people can find. In our experience the fix is almost never "ask for indexing" and almost always one of the silent failures below. Why does npx skills add say no matching skills found? + The two silent causes we hit ourselves: a YAML parse failure in the SKILL.md frontmatter, which makes the installer skip the file entirely, and a root SKILL.md shadowing a skills/ directory, which makes a seven-skill repo enumerate as one. A third documented cause is the custom-layout bug in issue #1716, where recognised path prefixes swallow files in unrecognised locations. The installer reports what it found, not what it skipped, so all three look like your skill simply does not exist. What breaks SKILL.md parsing most often? + An unquoted colon in the description. YAML reads "description: Share a page: a client" as a nested mapping and fails with "Nested mappings are not allowed in compact mappings". The listing can still render on skills.sh while every install silently skips the file, which is the worst of both worlds: you look listed and ship nothing. Quote any description containing a colon. How do skills rank on the skills.sh leaderboard? + By installs, counted through CLI telemetry (users can opt out with SKILLS_NO_TELEMETRY=1), with all-time, trending, and hot windows. Search matches the name and description text, so a description written in the words of the job ("publish HTML", "share a page privately") is findable and a description written in product language is not. The index is server-side and recrawls on its own schedule; edits take days, not minutes, to show. How should a multi-skill repo be laid out? + One skill per directory under skills//SKILL.md, and no SKILL.md at the repo root. The root file shadows the directory: our repo reported "Found 1 skill" until we moved the root skill into skills/publish/, after which the same command reported "Found 7 skills" with nothing else changed. Indexed multi-skill repos like anthropics/knowledge-work-plugins follow exactly this shape. Keep reading ## Related guides - [ The Stacktree skill What the skill in this story actually does: publish HTML from any agent to a private link. ](/skills) - [ Grok Bot explained The other agent surface we tested hands-on this month. ](/blog/what-is-grok-bot) - [ MCP 2026 spec changes Every breaking change in the July spec, with fixes. ](/blog/mcp-2026-spec-changes) - [ Every agent integration MCP, skills, n8n, connectors — all the ways agents publish to Stacktree. ](/agents) References ## Sources and further reading - [ vercel-labs/skills ↗ The CLI and ecosystem repo: 29K stars, and the 191 open "request indexing" issues this post exists to answer. ](https://github.com/vercel-labs/skills) - [ Issue #1716: custom-layout paths silently discarded ↗ The documented class of the shadowing failure, open with zero comments since July. ](https://github.com/vercel-labs/skills/issues/1716) - [ v1.5.23 release ↗ The 18 August release: stops extracting gh auth tokens, stops sending private repo identifiers to telemetry. ](https://github.com/vercel-labs/skills/releases/tag/v1.5.23) - [ Skill Packs announcement ↗ The 7 August bundling feature, currently without versioning or signatures. ](https://vercel.com/changelog/skill-packs-are-now-available) - [ skills.sh ↗ The leaderboard itself: all-time, trending, and hot windows. ](https://skills.sh/) ## The skill in the story. npx skills add stevysmith/stacktree-skill — publish HTML from any agent to a private link. [ Sign up free → ](https://app.stacktr.ee/?join=1&from=cta_blog_skills_sh_indexing_explained) install npx stacktree-install Copy Private hosting for the HTML your agents make. [](https://betalist.com/startups/stacktree?utm_campaign=badge-stacktree&utm_medium=badge&utm_source=badge-featured)[Featured on](https://devhunt.org/tool/stacktree)[](https://buildlist.io)[Get started free](https://app.stacktr.ee/?join=1) ## Product - [Templates](/templates) - [Example deliverables](/examples) - [Custom domains](/custom-domains) - [Client feedback](/client-feedback-loop) - [One-time links](/one-time-view-links) - [See how pages get read](/page-engagement) - [Made with Stacktree](/made-with) - [Security](/security) - [Watch the demo](/demo) ## Agents - [All integrations](/agents) - [Claude Code](/claude-code) - [OpenAI Codex](/codex) - [Cursor](/cursor) - [Claude.ai connector](/claude-ai-connector) - [MCP server](/mcp-publish-html) - [Deploy from Claude Code](/deploy-html-from-claude-code) - [Skills](/skills) - [Slack app](/slack) - [n8n node](/n8n) - [Agent payments (x402)](/x402) ## Alternatives - [All comparisons](/alternatives) - [Head-to-head comparisons](/compare) - [Tiiny Host](/tiiny-host-alternative) - [GitHub Pages (private)](/github-pages-private-alternative) - [Vercel](/vercel-alternative-for-agents) - [ngrok](/ngrok-alternative-for-html) - [Display.dev](/display-dev-alternative) - [Static.app](/static-app-alternative) - [OpenAI Codex Sites](/openai-codex-sites-alternative) - [here.now](/here-now-alternative) - [Shippage](/shippage-ai-alternative) - [Best private hosting](/best-private-html-hosting) ## Use cases - [All use cases](/use-cases) - [Share with clients](/share-with-clients) - [Send a file to a client](/share-html-file-with-client) - [Share Claude artifacts](/share-claude-artifacts) - [Share Jupyter notebooks](/share-jupyter-notebook-html) - [Host Storybook privately](/host-storybook-privately) - [Architecture diagrams](/share-architecture-diagrams) - [AI-generated reports](/host-ai-reports) - [Internal HTML tools](/internal-tool-hosting) - [Private HTML hosting](/private-html-hosting) - [Vibe-coded page hosting](/vibe-coding-hosting) - [Leave a website builder](/website-builder-migration) ## Learn - [Blog](/blog) - [Glossary](/glossary) - [FAQ](/faq) - [Agent-loop hosting](/agent-loop-hosting) - [Why agents need a publish primitive](/blog/why-agents-need-a-publish-primitive) - [MCP servers explained](/blog/mcp-servers-explained-for-developers) - [What changed in the 2026-07 MCP spec](/blog/mcp-2026-spec-changes) - [Sites in Codex explained](/blog/sites-in-codex-explained) - [Private-by-default hosting](/blog/private-by-default-html-hosting) - [An agent paid us $1 (x402)](/blog/agent-paid-to-provision-itself) - [When a loop hits a paywall](/blog/loop-engineering-paywall) - [Pricing](/pricing) - [Self-host (new)](/self-host) - [Changelog](/changelog) - [Docs](https://stacktr.ee/docs) - [About](/about) © 2026 Stacktree · stacktr.ee [Privacy](/privacy)[Terms](/terms)[Security](/security)[Dashboard](https://app.stacktr.ee)[npm](https://www.npmjs.com/package/stacktree-mcp)[Sitemap](/sitemap.xml)[llms.txt](/llms.txt)[API spec](/openapi.json) --- Full markdown summary of the Stacktree marketing surface: https://stacktr.ee/llms-full.txt