Skip to content
Skills Library
Marketing & content · Planning

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.

Licence
MIT
Last repository change
31.08.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 31.08.2026, without references to retired models or APIs.

Licence

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

found
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

  1. How discovery actually works (three lanes)
  2. Playbook — run in this order
  3. Gotchas (hard-won)
  4. Verify
Original SKILL.md headings · 73 lines, 605 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.