github-discoverability
/github-discoverability
Make a GitHub repo or Agent Skill discoverable across the skill-aggregator ecosystem — GitHub topics, scraper-visible SKILL.md paths, instant directories (awesomeskills.dev / SkillsMP), gh skill + agentskills.io conformance, and the MCP registry. Use when someone wants their skill or repo to be "found", indexed, listed in registries/directories, surfaced by skill scrapers, or asks how aggregators discover projects on GitHub.
- Author
- skill-federation ↗
- Repository
- skill-federation ↗
- Licence
- MIT
- Last repository change
- 31.08.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 31.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Make a GitHub repo or Agent Skill discoverable across the skill-aggregator ecosystem — GitHub topics, scraper-visible SKILL.md paths, instant directories (awesomeskills.dev / SkillsMP), gh skill + agentskills.io conformance, and the MCP registry. Use when someone wants their skill or repo to be "found", indexed, listed in registries/directories, surfaced by skill scrapers, or asks how aggregators discover projects on GitHub.
Triggers from the description
Original author description
Make a GitHub repo or Agent Skill discoverable across the skill-aggregator ecosystem — GitHub topics, scraper-visible SKILL.md paths, instant directories (awesomeskills.dev / SkillsMP), gh skill + agentskills.io conformance, and the MCP registry. Use when someone wants their skill or repo to be "found", indexed, listed in registries/directories, surfaced by skill scrapers, or asks how aggregators discover projects on GitHub.
How it works
- How discovery actually works (three lanes)
- Playbook — run in this order
- Gotchas (hard-won)
- Verify
SKILL.md preview
---
name: github-discoverability
description: Make a GitHub repo or Agent Skill discoverable across the skill-aggregator ecosystem — GitHub topics, scraper-visible SKILL.md paths, instant directories (awesomeskills.dev / SkillsMP), gh skill + agentskills.io conformance, and the MCP registry. Use when someone wants their skill or repo to be "found", indexed, listed in registries/directories, surfaced by skill scrapers, or asks how aggregators discover projects on GitHub.
allowed-tools: Bash, Read, Edit, WebFetch
---
# 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](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](https://www.awesomeskills.dev/en/submit) 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](reference.md) for exact commands, endpoints, the recommended topic set,
the mirror + drift-guard pattern, and the per-destination checklist.
Files in this package (2)
- SKILL.md 5 KB
- reference.md 4 KB
Versions
The database has no other skills named github-discoverability.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version f99e88e82d1c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100github-better-outreach
Writes a ready-to-run gh command that sets the 20 best GitHub topics, and a better description, for one repository. Use when a person asks for topics, tags, discoverability or outreach of a repository. - 100github-seo
Makes an open-source GitHub repo discoverable and safe to publish. Audits the repo name, description, topics and README for search, writes a search-ready README, runs a pre-publish secret and client-data check, and guides the launch sequence. Covers MCP server registry… - 100github-presence
When the user wants to optimize their GitHub profile, README, or project discoverability. Trigger phrases include "GitHub README," "README optimization," "GitHub profile," "GitHub stars," "GitHub discoverability," "awesome lists," or "GitHub marketing. - 100github-presence
When the user wants to optimize their GitHub profile, README, or project discoverability. Trigger phrases include "GitHub README," "README optimization," "GitHub profile," "GitHub stars," "GitHub discoverability," "awesome lists," or "GitHub marketing. - 100obsidian-plugin-seo
Use when the goal is to make an Obsidian plugin more discoverable through its metadata — the manifest.json/package.json description text that Obsidian's in-app community plugin browser and the community.obsidian.md plugin page search against, plus the GitHub repository's… - 100repo-readme-optimizer
Writes or audits a GitHub README and repo card (About line, topics, social preview) for an open-source tool, SDK, plugin or MCP server so it ranks in Google and gets cited by AI assistants. Use when asked to write a README, review a GitHub README, README best practices or make a repo rank.