agentsclimarketplace

Repo discoverability

Skill Paldom/github-skills/skills/repo-discoverability

Agent Skills for professional GitHub repos - brief, structured, SEO-friendly READMEs that convert visitors into users, plus complete OSS scaffolding: community health files, templates, and discoverability best practices.

Install
npx -y skills add Paldom/github-skills --skill repo-discoverability

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Optimizes how a GitHub repository gets found - repo description, topics, social preview image, name/H1 alignment, heading and link practices for GitHub and web search. Use when the user wants more stars, traffic, or search visibility, or asks to set topics, improve repo SEO, or make the project easier to find. Not for rewriting README prose or repo protections.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.9 KB, as published. Nobody here has run it

repo-discoverability

Tunes the metadata layer GitHub actually ranks and displays: repository description, topics, social preview, homepage, and the naming/heading signals search engines read. Models asked to "improve SEO" tend to keyword-stuff README prose; the real levers are repo settings most people never touch — this skill works those levers, with gh commands for each.

When NOT to use

  • Writing or restructuring README content → readme-author.
  • Community files, templates, protections → their focused skills.
  • Building a docs website (that's the web-tier; this skill only points to it).
  • Promotion/marketing advice (where to post) → out of scope.

Workflow

  1. Audit current state (read-only): 
    python3 "${CLAUDE_SKILL_DIR}/scripts/check_discoverability.py" [owner/repo]
    It reports description, topics, homepage, social preview, and H1 alignment status with pass/warn/fail per lever.
  2. Read references/discoverability-playbook.md, then fix in priority order:
    • Description (the About text and the search snippet): one sentence with plain category keywords + audience + outcome. ≤350 chars. gh repo edit <owner/repo> --description "..."
    • Topics: 5–10, covering category, language, use case, domain. Lowercase, hyphens, ≤35 chars each, only accurate ones — topics are browsable search surfaces, not tags for decoration. gh repo edit <owner/repo> --add-topic <t1> --add-topic <t2> ...
    • Name ↔ H1 alignment: README H1 should match or contain the repo name; if the repo name is cryptic, compensate in the description's first words.
    • Homepage: docs/demo URL if one exists: gh repo edit --homepage <url>.
    • Social preview: cannot be set via CLI — tell the user exactly: Settings → General → Social preview (1280×640; without it, shared links render as bare name + avatar).
    • Headings/links (hand off content edits to readme-author if substantial): task-based ## headings; descriptive anchor text, never "click here".
  3. Apply only after showing the user the before → after for description and topics; then re-run the check script to confirm.
  4. Two-tier reminder: full search control (title tags, meta descriptions, structured data) lives on a docs/Pages site, not the repo page. Say so when the user's ambitions exceed what repo metadata can do.

Output spec

Description, topics, and homepage set and verified via re-run of the check script; social-preview instruction delivered; any README-level naming misalignment either fixed (trivial) or delegated to readme-author. No inaccurate topic added.

Gotchas

  • Private repos are invisible to search — prepare metadata anyway so the public flip is turnkey, and say that's what you're doing.
  • GitHub search favors maintained repos: freshness (recent commits/releases) is a ranking signal no metadata can fake.
  • Vendor-blog conversion stats ("N× more stars") are directional at best — never promise numbers.
  • Keyword stuffing violates the people-first rule and reads as spam in the About box — every topic and keyword must be defensible.

Files

  • references/discoverability-playbook.md — the two-tier model, per-lever guidance, effort/return table, measurement (14-day traffic windows, views vs clones).
  • scripts/check_discoverability.py — read-only audit via gh; non-zero exit when required levers are missing.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.