Github discoverability

GitHub discoverability for Agent Skills

Get a repo or skill found by the tools people actually use to discover skills: automated scrapers, curated lists, and registries. This is a distribution playbook, not generic SEO — it targets the specific signals the skill ecosystem keys on.

Do it honestly. Real project, real value, one accurate entry per destination. Topics must be genuinely relevant; descriptions come from the actual SKILL.md. Keyword-stuffing topics or spraying low-effort PRs across many lists gets a project removed from curated lists — it's negative-sum. When a curator declines, that's their call; don't re-submit.

How discovery actually works (three lanes)

1. Automated scrapers (SkillsMP/awesomeskills.dev, GitHub /topics pages, gh skill). They key on GitHub topics and on SKILL.md files at conventional paths. Zero human in the loop — conform to the convention and you're indexed.
2. Curated "awesome" lists (VoltAgent, travisvn, ComposioHQ, tech-leads-club). Manual PRs, human review. Higher trust, but most reject brand-new skills and require social proof / real usage.
3. Registries (agentskills.io spec, registry.modelcontextprotocol.io for MCP servers). Conformance + being on GitHub is the entry condition.

Playbook — run in this order

1. Put SKILL.md where scrapers look. The single most common miss: the skill lives at a nested path (e.g. integrations/foo/skills/x/SKILL.md) that naive tree-walkers never reach. Scrapers expect root SKILL.md or skills/<name>/SKILL.md. If your canonical source lives elsewhere, mirror a committed copy to skills/<name>/ and guard it in CI so it can never drift (see reference.md → "Mirror + drift guard").

2. Set GitHub topics — the highest-leverage free signal; topic-scrapers and GitHub's own /topics/* pages both index them. Use the accurate core set (see reference.md). Set via gh repo edit --add-topic ... or the REST PUT /repos/{o}/{r}/topics.

3. Submit to instant directories. awesomeskills.dev/SkillsMP has a no-moderation submit form that auto-parses your SKILL.md. Paste the repo-root URL, not a subfolder deep-link — the auto-detector walks the tree, and deep-links can error while the root URL succeeds.

4. Conform to the open spec so gh skill search and agentskills.io index you: valid frontmatter (name + description minimum) and the SKILL.md-in-a-folder layout. No separate submission needed — conformance + public GitHub is the entry condition.

5. Publish to the MCP registry if you ship an MCP server: keep server.json in lockstep with the published npm version and run mcp-publisher. See reference.md.

6. Curated lists LAST, and only when mature. VoltAgent and travisvn explicitly reject just-created skills ("give your skill time to mature and gain users"). Submitting a day-old repo wastes goodwill and gets declined. Wait for stars/usage, then open one honest PR per list after reading its CONTRIBUTING.md and checking its interaction limits.

Gotchas (hard-won)

• Nested SKILL.md is invisible to convention scrapers → always expose a root-level path.
• awesomeskills.dev: submit the repo-root URL — its per-skill subfolder deep-link is unreliable (it errors, or silently accepts and never saves). Root URL indexes the repo's primary skill; extra skills in the same repo get picked up on their next crawl, not on submit.
• Curated lists gate on maturity — brand-new self-submissions are rejected by rule.
• Over-optimizing backfires — irrelevant topics and duplicate PRs get you delisted.
• A generated/mirrored copy will drift unless a CI check regenerates it and fails on diff.

Verify

• Topics: open https://github.com/topics/<topic> and confirm the repo appears.
• Directory: search the directory's site/API for the repo name.
• MCP registry: curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=<name>".
• Spec: gh skill search <name> (once the root SKILL.md is on the default branch).

See reference.md for exact commands, endpoints, the recommended topic set, the mirror + drift-guard pattern, and the per-destination checklist.