GitHub Repository Optimization

Transform any GitHub repository into a high-converting, SEO-optimized landing page that drives stars, followers, and traffic. Every repo you touch should look like a top-100 open source project.

This skill has two modes:

Optimize — rewrite a repo's README, metadata, and structure for maximum conversion
Advise — give the user a star growth strategy using the knowledge base below

Goals (in priority order)

Stars -- the primary social proof metric on GitHub
Followers -- drive traffic to the repo owner's social profiles
Discoverability -- rank in GitHub search, Google, and LLM answer engines
Traffic -- turn visitors into users/followers
Professional credibility -- signal quality through structure and polish

Step 0: User Configuration (Self-Updating)

Before optimizing, you need to know who owns this repo. This step runs once -- after that, the config is reused.

Check for existing config

Look for ~/.claude/skills/github-optimization/.config.yml. If it exists, load the values and skip to Step 1. Show the user what's loaded and ask if anything changed.

If no config exists, detect + ask

Detect automatically from git config and GitHub API:
- gh api user -- gets the authenticated GitHub username and profile URL
- gh api repos/<owner>/<repo> -- gets the repo owner (could be org or user)
- git config user.name -- gets the local git display name
Ask the user for anything you can't detect:
- Display name -- their real name or preferred attribution (e.g., "Jane Smith")
- X/Twitter handle -- for the Follow badge (e.g., "@janesmith"). If they don't want it, skip it.
- Company or organisation -- for footer attribution (optional)
- Company URL -- link for the company name (optional)
- Website URL -- personal or company site (optional)
Save the config to ~/.claude/skills/github-optimization/.config.yml:

# GitHub Optimization Skill — User Config
# This file is auto-generated. Edit anytime.
author_name: "Jane Smith"
author_github: "janesmith"
x_handle: "janesmith"          # leave empty string "" to skip Follow badge
company_name: "Acme Corp"      # leave empty string "" to skip
company_url: "https://acme.com"
website_url: "https://janesmith.dev"

Use these variables throughout the pipeline:
- {OWNER} -- GitHub username or org (from repo URL, detected per-repo)
- {REPO} -- repository name (detected per-repo)
- {AUTHOR_NAME} -- from config
- {AUTHOR_GITHUB} -- from config
- {X_HANDLE} -- from config (may be empty)
- {COMPANY_NAME} -- from config (may be empty)
- {COMPANY_URL} -- from config (may be empty)
- {WEBSITE_URL} -- from config (may be empty)

If any field is empty, omit that element entirely from the output. No empty placeholders or broken badges.

Updating config

If the user says "update my config", "change my X handle", or similar, update the .config.yml file and confirm the change.

The Optimization Pipeline

0. CONFIG       -> Load or create user config (runs once, self-updates)
1. AUDIT        -> Read current README, description, topics, repo structure
2. KEYWORDS     -> Identify target search terms for this repo's domain
3. METADATA     -> Optimize repo name, description (About), and topics
4. README       -> Rewrite as a landing page following the template below
5. HUMANISE     -> Run the humanise-text skill on all prose to strip AI patterns
6. EXTRAS       -> Add LICENSE, CONTRIBUTING.md if missing
7. PUBLISH      -> Commit, push, apply gh repo edit for description/topics

Skill Chaining

This skill calls other skills during execution:

humanise-text -- After drafting the README, invoke the humanise-text skill on all prose sections. This strips AI writing patterns and makes the copy sound like a real person wrote it. Non-negotiable -- every README must pass through this.

Step 1: Audit

Read the current state:

README.md content and structure
Repo description (About section)
Topics/tags
License
File structure
Any existing badges

Note what's missing, what's weak, what's good.

Step 2: Keyword Research

Identify 3-5 target keywords that developers would search for to find this project. Consider:

What problem does this solve?
What technology does it use?
What domain is it in?

These keywords must appear in: repo name (if possible), About description, README H1 and H2 headers, and topic tags.

Step 3: Metadata Optimization

About Description

Under 120 characters ideal, max 250
Lead with what it does, not what it is
Include primary keyword naturally
Format: <Action verb> <what> for <who/what>. <Key differentiator>.

Topic Tags

Select 10-20 tags across three categories:

Purpose tags -- what the project does
Tech stack tags -- technologies used
Domain tags -- field or industry

Apply with:

gh repo edit {OWNER}/{REPO} --add-topic tag1 --add-topic tag2 ...

Step 4: README Rewrite

The README is a landing page, not documentation.

README Template

Adapt badges based on what user info is available in the config:

<div align="center">

# <Project Name>

**<One-line pitch -- what it does in plain English>**

<br />

[![Star this repo](https://img.shields.io/github/stars/{OWNER}/{REPO}?style=for-the-badge&logo=github&label=%E2%AD%90%20Star%20this%20repo&color=yellow)](https://github.com/{OWNER}/{REPO}/stargazers)

If {X_HANDLE} is set, add next to the star badge:

&nbsp;&nbsp;
[![Follow @{X_HANDLE}](https://img.shields.io/badge/Follow_%40{X_HANDLE}-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/{X_HANDLE})

If {X_HANDLE} is empty, skip the Follow badge entirely.

Then continue with credential badges:

<br />

[![<Badge 1>](shields-url)](<link>)
&nbsp;
[![<Badge 2>](shields-url)](<link>)

---

<One paragraph pitch. What pain does this solve? Why should someone care?>

[Install](#install) | [How It Works](#how-it-works) | [Features](#features) | [Contributing](#contributing)

</div>

Badge Rules

Row 1 (CTAs -- large, prominent):

Star badge with live count -- ALWAYS first, style=for-the-badge, yellow
Follow on X badge -- ONLY if {X_HANDLE} is set

Row 2 (Credential badges -- same size):

All badges use style=for-the-badge -- never mix sizes
Pick 2-4 relevant: License, PRs Welcome, language/framework, build status

Section Order

Why This Exists / The Problem -- 2-3 sentences on the pain point
Before vs After (optional) -- comparison table
Install / Quick Start -- under 5 steps, one command ideal
How It Works -- visual workflow (ASCII diagram, table, or numbered steps)
Features / Use Cases -- table or bullet list, scannable
What's Inside / Structure -- file tree if relevant
Configuration / Options (optional)
Security (optional)
Contributing -- short, welcoming
License -- one line
Footer with CTAs -- star + follow badges repeated

Footer Template

Build dynamically from config:

---

<div align="center">

Attribution line -- build from available config fields:

If author + company + website: Built by [NAME](GITHUB) at [COMPANY](COMPANY_URL) | [WEBSITE](WEBSITE_URL)
If author + company (no website): Built by [NAME](GITHUB) at [COMPANY](COMPANY_URL)
If author + website (no company): Built by [NAME](GITHUB) | [WEBSITE](WEBSITE_URL)
If author only: Built by [NAME](GITHUB)
If nothing: Built with the github-optimization skill

<br />

**If this is useful to you:**

[![Star this repo](star-badge-url)](stargazers-url)

If {X_HANDLE} exists, add Follow badge here too.

</div>

Writing Rules

Non-negotiable. These define the voice.

github-optimization