# Github Optimization

> Optimize any GitHub repo for maximum stars, traffic, followers, and discoverability. Rewrites README as a high-converting landing page with SEO-optimized headers, shields.io badges, star/follow CTAs, keyword-rich description and topics, humanized copywriting, and author attribution. Includes a star growth knowledge base with launch strategies, channel playbooks, and ROI rankings. Use when user sa…

- **Type:** Skill
- **Install:** `agentstack add skill-199-biotechnologies-github-optimization-skill-github-optimization-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [199-biotechnologies](https://agentstack.voostack.com/s/199-biotechnologies)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [199-biotechnologies](https://github.com/199-biotechnologies)
- **Source:** https://github.com/199-biotechnologies/github-optimization-skill

## Install

```sh
agentstack add skill-199-biotechnologies-github-optimization-skill-github-optimization-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
1. **Optimize** — rewrite a repo's README, metadata, and structure for maximum conversion
2. **Advise** — give the user a star growth strategy using the knowledge base below

## Goals (in priority order)

1. **Stars** -- the primary social proof metric on GitHub
2. **Followers** -- drive traffic to the repo owner's social profiles
3. **Discoverability** -- rank in GitHub search, Google, and LLM answer engines
4. **Traffic** -- turn visitors into users/followers
5. **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

1. **Detect automatically** from git config and GitHub API:
   - `gh api user` -- gets the authenticated GitHub username and profile URL
   - `gh api repos//` -- gets the repo owner (could be org or user)
   - `git config user.name` -- gets the local git display name

2. **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)

3. **Save the config** to `~/.claude/skills/github-optimization/.config.yml`:

```yaml
# 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"
```

4. **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: `  for . .`

### Topic Tags
Select 10-20 tags across three categories:
1. **Purpose tags** -- what the project does
2. **Tech stack tags** -- technologies used
3. **Domain tags** -- field or industry

Apply with:
```bash
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:

```markdown

# 

****

[](https://github.com/{OWNER}/{REPO}/stargazers)
```

**If {X_HANDLE} is set, add next to the star badge:**
```markdown
  
[](https://x.com/{X_HANDLE})
```

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

Then continue with credential badges:
```markdown

[]()
 
[]()

---

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

```

### 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

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

### Footer Template

Build dynamically from config:

```markdown
---

```

**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`

```markdown

**If this is useful to you:**

[](stargazers-url)
```

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

```markdown

```

---

## Writing Rules

Non-negotiable. These define the voice.

### DO:
- Write like a human explaining to a friend. Short sentences. Active voice.
- Lead every section with the value, not the mechanism
- Use "you" and "your" -- speak directly to the reader
- Be specific over abstract
- Keep paragraphs to 2-3 sentences max
- Use tables for comparisons

### DO NOT:
- Use AI slop: "leverage", "streamline", "empower", "seamlessly", "robust", "cutting-edge", "revolutionize", "harness the power of", "elevate your workflow", "supercharge"
- Start sentences with "This project..." or "This tool..."
- Write walls of text
- Use passive voice
- Add filler words: "basically", "essentially", "simply", "just"
- Use exclamation marks

### SEO in Headers:
- H1 must contain the primary keyword
- H2s should contain secondary keywords naturally
- Write for humans first, but be deliberate about placement

---

## Step 5: Extras

Add if missing:
- **LICENSE** -- MIT unless user specifies otherwise
- **CONTRIBUTING.md** -- short, welcoming, 3-step process

Do NOT add unless asked: CODE_OF_CONDUCT.md, SECURITY.md, .github/ISSUE_TEMPLATE/

## Step 6: Publish

1. Commit all changes with a descriptive message
2. Push to remote
3. Update repo metadata via `gh repo edit`
4. Report to user: what changed, the new description, topics added, live URL

---

## Checklist Before Done

- [ ] Config loaded or created (no hardcoded usernames anywhere)
- [ ] Star badge with live count at top
- [ ] Follow badge ONLY if user has X handle configured
- [ ] All badges same size (for-the-badge)
- [ ] One-line pitch under H1
- [ ] README reads like a landing page
- [ ] No AI slop words
- [ ] Install section under 5 steps
- [ ] Visual element present (diagram, table, or file tree)
- [ ] H1/H2 contain target keywords
- [ ] About description under 120 chars
- [ ] 10-20 topic tags
- [ ] Footer repeats CTAs with correct user attribution
- [ ] LICENSE exists
- [ ] No broken links
- [ ] Committed and pushed

---

# Star Growth Knowledge Base

When users ask "how do I get more stars?", "launch strategy", "promote my repo", or similar, use this knowledge base to advise them. This section is reference material, not part of the optimization pipeline.

## Channel Rankings (by ROI)

| Rank | Tactic | Effort | Expected Stars | Risk |
|---|---|---|---|---|
| 1 | **Stacked launch** (HN + Reddit + X + PH same day) | High (1 day prep) | 200-2,000+ | None |
| 2 | **Awesome list submissions** | Low (PRs) | Slow burn, compounds | None |
| 3 | **README optimization + social preview** | Medium (1 hour) | 3x multiplier on all other efforts | None |
| 4 | **GitHub SEO** (name, topics, description) | Low (30 min) | Passive long-term discovery | None |
| 5 | **Demo GIF/video in README** | Medium | Dramatically higher conversion | None |
| 6 | **Create your own awesome list** | Medium | Slow burn + cross-promote | None |
| 7 | **Newsletter submissions** | Low (emails) | 50-500 per feature | None |
| 8 | **YouTube tutorials** | High | Best sustained long-term driver | None |
| 9 | **Reciprocal listicle on X** | Low | Network-dependent | None |
| 10 | **Hacktoberfest tagging** (October) | Low | 50-200 seasonal | Spam PRs |
| 11 | **Discord/community building** | High ongoing | Retention/advocacy | None |
| 12 | **Conference talks** | High | Low direct, high compounding | None |

## Hacker News Playbook

**Best time:** Tuesday-Thursday, 8-10 AM Pacific. Sunday 6-9 PM Pacific for lower competition.

**Title format:** `Show HN: [Name] — [What it does concretely]`

**What works:** Write like a peer, not a marketer. No buzzwords. Lead with the problem. Respond to every comment in the first hour. Post your own substantive first comment within 5 minutes.

**Thresholds:** 8-10 genuine upvotes + 2-3 thoughtful comments in first 30 minutes to crack top 10.

**Account requirements:** 250+ karma with technical comment history for best results. Fresh accounts face moderation.

**Ring detection is aggressive.** Never tweet "please upvote my HN post." Use private channels (email, Slack, Discord) to notify people.

**Real results:**
- Lago: #1 for 48+ hours, primary driver to 1,000 stars
- Encore: 1,500 stars in one week from a single Show HN
- Average: 121 stars in 24 hours, 289 in one week

## Reddit Playbook

**Build karma 2+ weeks before posting.** Reddit's 90/10 rule: 90% genuine activity, 10% self-promotion.

| Subreddit | Notes |
|---|---|
| r/SideProject (453K) | Explicitly allows self-promo |
| r/programming (6M+) | Strict anti-promo, "how we built X" works |
| r/selfhosted (500K+) | Converts extremely well |
| r/webdev | "Showoff Saturday" only |
| r/opensource | Link-friendly, lower volume |
| r/coolgithubprojects | Specifically for GitHub repos |

**Expected:** 50-300 stars per successful post. Tailor messaging per subreddit.

## Product Hunt Playbook

**Voting resets:** 12:01 AM PST daily. Upvotes hidden first 4 hours.

**Upvotes for #1:** 600-800 weekday, 400-600 weekend.

**Best days:** Tuesday-Thursday.

**Expected:** 200-1,000 stars from top-5 Product of the Day. #1 can deliver 500-2,000+.

**Timeline:**
- 4-6 weeks out: Build 200-500 email subscribers
- 1 week out: Prepare all assets
- Launch day: Go live 12:01 AM PST, reply to everything, email blast 6 AM PST

## Twitter/X Playbook

**What works:** Short demo videos/GIFs outperform text. Tweets from supporters drive more stars than self-tweets. Weekday mornings US time (9-11 AM ET).

**Expected:** 7% increase in starring from tweeting. Viral video tweets can hit 1,600 stars in 6 hours.

## The Stacked Launch Strategy

The meta-strategy every fast-growing repo used:

| Timing | Action | Expected Stars |
|---|---|---|
| Week before | Submit to newsletters (TLDR, Console.dev, Changelog) | -- |
| Launch day AM | Post HN "Show HN" (Tue-Wed, 8-11am ET) | 121 avg, up to 1,500 |
| Launch day PM | Post Reddit (r/programming, r/selfhosted, domain sub) | 50-300 |
| Launch day | Tweet demo video + get supporters to share | 50-500+ |
| Launch day | Product Hunt launch | 200-1,000 |
| Day 2-3 | GitHub Trending triggers from combined velocity | 200-2,000+ |
| Week after | Publish "how I built X" on Dev.to | 20-100 + SEO tail |

## GitHub Trending Algorithm

Measures **star velocity relative to your historical average**, not absolute numbers. A repo averaging 2 stars/day that gets 20 will trend faster than one averaging 50 that gets 60. Updates ~10-11 AM UTC daily.

## GitHub SEO

- **Repo name is the H1 tag.** `ai-chatbot-framework` ranks for "chatbot framework." Self-descriptive beats clever.
- **About description** appears in Google snippets and GitHub topic pages. Treat it like a meta description.
- **Topic tags (10-20):** Most underoptimized field. Mix purpose, tech stack, and industry.
- **Freshness signal:** Even small commits keep you alive in search rankings.

## Awesome Lists Strategy

Submit to relevant awesome lists via PR. Key requirements for sindresorhus/awesome:
- 30-day minimum age from first real commit
- Not AI-generated content
- Review 4 other open PRs before submitting
- Main branch named `main`

Creating your own awesome list is also effective:
1. Pick a niche you own
2. Seed with 30-50 quality entries including your repos
3. Submit your list to meta-lists
4. Make contributing easy with fast PR merges

## Newsletter Directory

| Newsletter | How to Submit |
|---|---|
| Console.dev | Email hello@console.dev |
| Changelog News | changelog.com/news/submit |
| JavaScript Weekly | Email editor@cooperpress.com |
| PyCoder's Weekly | pycoders.com/submissions |
| This Week in Rust | PR on github.com/rust-lang/this-week-in-rust |
| DevOps Weekly | devopsweekly.com |
| TLDR | Paid only: advertise.tldr.tech |

## Growth Hacks (Quick Wins)

1. **Social preview image** -- Settings > Social Preview. Determines click-through on every share.
2. **Demo GIF in first screenful** -- highest-impact README element
3. **Star-bait at moment of value** -- CLI prompt after successful install, not before
4. **Reciprocal listicles** -- "Top 10 tools for X" on X, tag maintainers. Many reshare.
5. **GitHub profile as funnel** -- pin 6 best repos, profile README as landing page
6. **Hacktoberfest tagging** -- October, `hacktoberfest` tag, 50-200 stars
7. **Milestone giveaways** -- at 1k stars, star + follow + tag friends
8. **GitHub Actions Marketplace** -- publishing an action creates permanent listing
9. **Cross-repo linking** -- link between your repos in READMEs and "See Also" sections
10. **All Contributors bot** -- adds people to README table, creates investment/advocacy

## Cold Start: First 100 Stars

First 100 come from people you know. Direct messages, personal asks (~60% conversio

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [199-biotechnologies](https://github.com/199-biotechnologies)
- **Source:** [199-biotechnologies/github-optimization-skill](https://github.com/199-biotechnologies/github-optimization-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-199-biotechnologies-github-optimization-skill-github-optimization-skill
- Seller: https://agentstack.voostack.com/s/199-biotechnologies
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.