github-seo

---
name: github-seo
description: 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 submissions (Official MCP Registry, Smithery, Glama, mcp.so). Use when the user wants more stars, traffic or search visibility for a repo, is about to open-source a project, asks for GitHub SEO or repo SEO, or wants to publish an MCP server. Not for general website SEO.
license: MIT
---

# GitHub SEO

A playbook for getting an open-source repo found, ranked and cited, in the right order.
Built from SERP research plus standard open-source practice.

## Evidence labels

Every claim in this skill and its references carries one of three labels. Keep them when you
report back, and never upgrade a label without a source.

- **verified**: checked against a primary source or a live search result, with a date.
- **observed**: seen in a real result at a point in time, not a documented rule. Re-check before relying on it.
- **general**: common open-source practice, not tested here. State it as practice, not fact.

GitHub does not publish its search ranking algorithm. Treat any "GitHub ranks X" statement as inference.

## Step 0: pick the path

- **Path A, plain GitHub repo**: a template, starter, benchmark harness, CLI, library or skill.
- **Path B, MCP server**: the project defines tools or resources over the Model Context Protocol
  (look for `server.json`, `mcp.json` or an MCP SDK dependency). Do Path A first, then Step B.

If unsure, check whether the repo exposes MCP tools. If it does, it is Path B plus Path A.

## Step 1: safety pass (mandatory, before anything goes public)

Never skip this, and never let distribution excitement jump ahead of it.

1. Confirm the repo holds no private client code, client names, store domains, internal ticket
   keys, API details specific to a client, or personal data about contractors or employees.
2. Scan the **full git history**, not only the current tree. A key committed and later deleted is
   still recoverable. Use `gitleaks detect --source . -v` when installed; otherwise use the grep
   in `references/publish-safety.md`.
3. If anything questionable appears, stop and tell the repo owner. The public or private call is theirs.
4. Settle the repo name now. Renaming after links accrue is costly (see Step A.1).

Details and the publish-or-not framework: `references/publish-safety.md`.

## Step 1b: repo security and permissions (report only)

Public does not mean safe to push to. Check who can change the default branch and the Pages
publishing branch, and which security features are on. Run
`python3 scripts/check_repo_seo.py owner/repo --security-only`. It covers branch rules (PR
required, deletion and force-push blocked), the Pages branch, secret scanning, push protection,
Dependabot, private vulnerability reporting and Actions token permissions. Items that need admin
print MANUAL: say "could not check, needs admin" and ask the owner. Never change settings
yourself, only recommend. Commands and evidence labels: `references/repo-security-checklist.md`.

## Step 2: audit what exists

Run the read-only audit. It needs the GitHub CLI (`gh`) logged in.

```bash
python3 scripts/check_repo_seo.py owner/repo
```

It reports pass, warn or fail for the description, topics, homepage, license, README shape,
and community files, then runs the security section from Step 1b (skip it with
`--skip-security`), and prints the one lever it cannot check (the social preview image).
Fix failures first, then warnings.

## Step A: plain repo checklist

1. **Slug.** Use a keyword-bearing name, not an internal codename. The slug appears in the page
   title as `owner/repo-name` [observed, 2026-08-08, two top-ranking repos in one SERP].
   Rename before the repo is public. If it is already public and linked, prefer fixing the
   description and H1 over a rename.
2. **README.** Write it from `references/readme-template.md`: 400 to 700 words, keyword-bearing
   H1, a first paragraph that works as a search snippet [observed], a copy-pasteable quickstart.
3. **About box.** One sentence description with the platform nouns people type, the Website
   field set to the canonical write-up, and topics that are accurate (GitHub allows up to 20).
   Field guidance: `references/general-github-seo.md` [general].
4. **License and contributor files.** Add a `LICENSE` (no license reads as "do not use this"),
   `CONTRIBUTING.md` and `SECURITY.md`.
5. **Social preview.** Upload a 1280 by 640 image in Settings, General. GitHub offers no CLI or
   API for it, so tell the owner exactly where to click.
6. **Pin** the repo on the organisation profile and on the maintainer's personal profile.
7. **Canonical write-up.** Publish a long-form post on a domain you own before any community
   post. Community posts link to it, not to the bare repo. If the repo makes a measurable claim,
   put a results table in the post: structured tables from independent-looking domains are what
   comparison-style AI answers tend to cite [observed].
8. **Launch** in the order in `references/distribution-sequence.md`. Order matters; each step
   produces the artifact the next needs.
9. **Upstream galleries and awesome-lists** only once the repo is complete and has real stars.
   Maintainers reject cold, thin submissions.
10. **Claude plugin directory.** If the repo ships a Claude plugin, follow
    `references/claude-plugin-directory.md` for the submission portal, Validate findings and
    the other plugin distribution routes.

## Step B: MCP server checklist (after Step A)

Start with `references/mcp-install-and-metadata.md`: choose the package type (npm, PyPI, OCI and
others each have their own ownership check), complete `server.json` including `websiteUrl`, and
lay out the README install routes per client. Then use `references/mcp-registry-checklist.md`. It covers the Official MCP Registry (`server.json`
plus the `mcp-publisher` CLI), Smithery, Glama, mcp.so, mcpservers.org, Cursor Directory, which
registries auto-ingest from the Official one, and common gotchas (stale listings under a personal
account, publish order, domain presence). Pitfalls from real runs (org namespace 403, OCI
build and label, leaked-history scrub) are in the install reference.

## What not to do

- Do not buy stars or run star-for-star swaps. The one visible signal is also the one that gets accounts banned.
- Do not post identical promotional text across subreddits, and do not post in r/programming or r/webdev (see the distribution reference for the posture).
- Do not budget citation lift on `llms.txt`. It is a 20 minute add, not a strategy [observed: a cited study found 97% of such files got zero AI-agent requests].
- Do not publish a benchmark that documents an unfixed live defect in someone's shipping product. Fix it first, then publish the general finding.
- Do not keyword-stuff the About box or topics. Every keyword must be defensible and accurate.
- Do not state registry behaviour or ranking mechanics as fact without a source. Flag it as an assumption.

## Reporting back

When you finish, give the owner three lists: what you changed, what only they can do (social
preview upload, pinning, account-bound registry logins, repo security settings you recommended),
and which advice is verified, observed or general. List every security check that returned
MANUAL as unchecked, not as passed.

• SKILL.md 7 KB
• evals/evals.json 5 KB
• references/claude-plugin-directory.md 5 KB
• references/distribution-sequence.md 4 KB
• references/general-github-seo.md 3 KB
• references/mcp-install-and-metadata.md 11 KB
• references/mcp-registry-checklist.md 4 KB
• references/publish-safety.md 3 KB
• references/readme-template.md 3 KB
• references/repo-security-checklist.md 4 KB
• scripts/check_repo_seo.py 13 KB