Github

GitHub -- Repository Optimization Suite

Comprehensive GitHub optimization across SEO, legal, community, and discoverability. Orchestrates 8 specialized sub-skills and 6 scoring workers: Claude Code subagents or Codex multi-agents. Data-first: every recommendation traces back to a data source.

Quick Reference

Prerequisites

Before any skill can operate, check these in order:

1. Git installed? Run git --version. If missing, guide user to install.
2. GitHub CLI installed? Run gh --version. If missing: winget install GitHub.cli (Windows) or brew install gh (macOS).
3. Authenticated? Run gh auth status. If not logged in, guide through gh auth login.
4. In a git repo? Run git rev-parse --is-inside-work-tree. If not, ask if they want to create one or point to an existing repo.

If a user has no GitHub account, direct them to https://github.com/signup and wait for them to complete signup before proceeding with gh auth login.

API Credentials

Two recommended services power SEO research and banner generation. The install script walks users through setting both up during installation. If they skipped setup, Step 0 below will catch it and guide them before any skill runs.

1. DataForSEO (MCP server -- NOT .env) DataForSEO provides live keyword and SERP data. It runs as an MCP server The install script handles this automatically. When configured, tools like dataforseo_labs_google_keyword_suggestions are available directly in conversation. If the MCP server is not configured, SEO skills fall back to codebase analysis.

2. KIE.ai (REST API -- uses .env) KIE.ai generates banner images for READMEs. It requires an API key in a .env file.

Standard dotenv locations: Check these paths in order:

1. Current working directory: ./.env.local, then ./.env
2. Skill root: github/.env.local, then github/.env
3. User home: ~/.env.local, then ~/.env

Loading credentials: Before banner generation, load the .env:

for envfile in ./.env.local ./.env github/.env.local github/.env ~/.env.local ~/.env; do
  if [ -f "$envfile" ]; then
    export $(grep -v '^#' "$envfile" | xargs) 2>/dev/null
    break
  fi
done

Shared Data Cache

Skills persist their outputs to .github-audit/ so other skills can reuse data without re-gathering. The orchestrator writes repo-context.json after baseline gathering. Each sub-skill reads cached data before gathering and writes its own cache file after executing.

Reference: Read github/references/shared-data-cache.md for JSON schemas, dependency map, and freshness rules.

Orchestrator responsibilities: Cache writes are embedded directly in Step 2 and Step 3.5 below -- look for the CACHE: callouts in each step.

Headless Contract

For API agents and non-interactive runners, use the deterministic script entrypoint:

python3 scripts/run_headless.py verify --mode both --path /path/to/repo
python3 scripts/run_headless.py audit --path /path/to/repo
python3 scripts/run_headless.py seo --path /path/to/repo
python3 scripts/run_headless.py legal --path /path/to/repo
python3 scripts/run_headless.py legal --path /path/to/repo --write-files
python3 scripts/run_headless.py meta --path /path/to/repo
python3 scripts/run_headless.py community --path /path/to/repo
python3 scripts/run_headless.py community --path /path/to/repo --write-files
python3 scripts/run_headless.py readme --path /path/to/repo
python3 scripts/run_headless.py readme --path /path/to/repo --generate-assets
python3 scripts/run_headless.py release --path /path/to/repo
python3 scripts/run_headless.py release --path /path/to/repo --write-files
python3 scripts/run_headless.py empire --path /path/to/repo
python3 scripts/run_headless.py empire --path /path/to/repo --generate-avatar
python3 scripts/run_headless.py cache-status --path /path/to/repo

The deterministic commands write:

• .github-audit/repo-context.json
• .github-audit/audit-data.json
• .github-audit/seo-data.json
• .github-audit/legal-data.json
• .github-audit/community-data.json
• .github-audit/meta-data.json
• .github-audit/readme-data.json
• .github-audit/releases-data.json
• .github-audit/empire-data.json
• .github-audit/output/<repo>-<timestamp>/GITHUB-AUDIT-REPORT.md
• .github-audit/output/<repo>-<timestamp>/ACTION-PLAN.md
• .github-audit/output/<repo>-<timestamp>/SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/SEO-REPORT.md
• .github-audit/output/<repo>-<timestamp>/SEO-SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/LEGAL-REPORT.md
• .github-audit/output/<repo>-<timestamp>/LEGAL-PLAN.md
• .github-audit/output/<repo>-<timestamp>/LEGAL-SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/COMMUNITY-REPORT.md
• .github-audit/output/<repo>-<timestamp>/COMMUNITY-PLAN.md
• .github-audit/output/<repo>-<timestamp>/COMMUNITY-SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/META-REPORT.md
• .github-audit/output/<repo>-<timestamp>/META-SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/README-REPORT.md
• .github-audit/output/<repo>-<timestamp>/README-PREVIEW.md
• .github-audit/output/<repo>-<timestamp>/README-SUMMARY.json
• .github-audit/output/<repo>-<timestamp>/RELEASE-REPORT.md
• .github-audit/output/<repo>-<timestamp>/RELEASE-PROPOSAL.md
• .github-audit/output/<repo>-<timestamp>/RELEASE-SUMMARY.json
• .github-audit/output/<owner>-<timestamp>/EMPIRE-REPORT.md
• .github-audit/output/<owner>-<timestamp>/EMPIRE-BLUEPRINT.md
• .github-audit/output/<owner>-<timestamp>/PROFILE-README-DRAFT.md
• .github-audit/output/<owner>-<timestamp>/EMPIRE-SUMMARY.json

run_headless.py seo is a deterministic fallback cache seeding path. It does not call DataForSEO MCP, so live volume, difficulty, intent, AI visibility, and SERP checks remain part of the interactive github seo skill flow.

run_headless.py legal is a deterministic legal planning path. By default it emits a compliance report plus legal-data.json without mutating the repo. Use --write-files to create or refresh LICENSE, SECURITY.md, CITATION.cff, and NOTICE when the plan marks them as missing or weak. Complex legal edge cases remain explicitly flagged for human review rather than being guessed.

run_headless.py meta is a deterministic metadata planning path. It writes a machine-readable metadata plan and only mutates live repo settings when explicitly invoked with --apply.

run_headless.py community is a deterministic community-health planning path. By default it scores the current Community Standards surface and emits a file plan without mutating the repo. Use --write-files to create or refresh deterministic community-health files, including YAML issue templates and YAML discussion category forms when discussion category slugs are discoverable.

run_headless.py readme is a deterministic README planning path. By default it builds a scored preview and cache without rewriting README.md. Use --write to save the generated README to disk. Use --generate-assets to reuse an existing banner, generate a KIE-backed banner when needed, and emit a generated social-preview.jpg plus file/raw/settings links for the final platform step.

run_headless.py release is a deterministic release planning path. By default it emits a release dashboard, proposal, and releases-data.json cache without mutating the repo. Use --write-files to prepare CHANGELOG.md and .github/release.yml. Use --create-release for explicit draft creation, and add --publish only when you intentionally want a live release created.

run_headless.py empire is a deterministic portfolio planning path. It writes empire-data.json, an empire blueprint, a profile README draft, and explicit gh commands for safe follow-up execution. Use --generate-avatar when you want the headless runner to generate assets/avatar.jpg; pin ordering and the final profile-photo upload remain explicit GitHub web UI steps.

Orchestration Logic

Step 0: Setup Check (runs ONCE per session, before anything else)

Before routing to any sub-skill, check if the user has the recommended services configured. This runs the FIRST time any github orchestration request is used in a session. After showing the setup status once, do not repeat it.

Check 1 -- DataForSEO MCP: Use ToolSearch to look for dataforseo_labs_google_keyword_suggestions.

Check 2 -- KIE.ai API Key:

for envfile in ./.env.local ./.env github/.env.local github/.env ~/.env.local ~/.env; do
  if [ -f "$envfile" ] && grep -q 'KIE_API_KEY=.' "$envfile" 2>/dev/null; then
    echo "KIE_CONFIGURED=true"; break
  fi
done

(Check that the key is not just present but has a non-empty value after the =.)

If BOTH are configured: Show a one-liner and move on:

Services: DataForSEO [active] | KIE.ai [active] -- full power mode.

If one or both are missing, STOP and show the setup guide:

## Setup Check

This suite works best with two recommended services. Here's your status:

DataForSEO  [not configured]  -- powers live keyword research, SERP rankings, and AI visibility
KIE.ai      [not configured]  -- powers AI-generated banner images for READMEs

### How to set up DataForSEO (5 minutes)

1. Create a free account at https://dataforseo.com
   (free tier includes enough credits for hundreds of keyword analyses)
2. Go to https://app.dataforseo.com/api-access to find your login and password
   - macOS/Linux: bash extensions/dataforseo/install.sh
   - Windows: powershell -File extensions\dataforseo\install.ps1
   The installer will prompt for your credentials and configure the MCP server.

### How to set up KIE.ai (2 minutes)

1. Go to https://kie.ai/api-key and create a free account
2. Copy your API key
3. Paste it into `./.env.local` (preferred) or `github/.env`:
   KIE_API_KEY=your_key_here

Want to set these up now, or continue without them?
(Skills still work without these services, but SEO recommendations will be
less precise and banner generation won't be available.)

Wait for the user to respond before proceeding. If they say continue/skip/later, proceed normally. If they want to set things up, guide them through it.

Step 1: Capture User Intent

On first interaction, ask conversationally what they want to accomplish. Map to one of:

If the user skips intent, fall back to repo-type defaults.

Step 2: Gather Baseline Data

For any repo, collect:

• gh repo view --json name,description,url,homepageUrl,repositoryTopics,visibility,defaultBranchRef,licenseInfo,stargazerCount,forkCount,watchers,primaryLanguage,createdAt,updatedAt
• File existence: README.md, LICENSE, CONTRIBUTING.md, SECURITY.md, CITATION.cff, CODE_OF_CONDUCT.md, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md, .github/FUNDING.yml, .gitattributes, CHANGELOG.md
• Codebase scan for repo-type detection

CACHE: After gathering, write .github-audit/repo-context.json with all baseline data. Create the directory and gitignore entry first:

mkdir -p .github-audit
grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore

Step 3: Detect Repo Type

Step 3.5: SEO Data Pass (DataForSEO Integration)

This step runs automatically when the DataForSEO MCP server is available. It discovers keyword opportunities that all downstream skills consume. If the MCP server is not configured, this step is skipped and skills use fallback methods.

How to check availability: Use ToolSearch to look for dataforseo_labs_google_keyword_suggestions. If it exists, the MCP server is running. Do NOT waste an API call just to test availability.

When to run: Before routing to ANY content-producing sub-skill (readme, meta, seo, empire). Skip for legal, community, releases (they don't need keyword data).

Important context: GitHub repos are NOT traditional websites. We don't scan a domain -- we discover what keywords people Google where a well-optimized GitHub repo could rank, then place those keywords in the README, description, and topics. See the github-seo skill for the full Keyword Opportunity Framework.

Cost and auto-run behavior:

• Each keyword_suggestions call costs ~3-5 cents
• Each serp_organic_live_advanced call costs ~5-8 cents
• Typical per-repo cost: 2 keyword calls + 1 SERP = ~10-15 cents

For single repos and small portfolios (1-5 repos): Just run it automatically. The cost is under 75 cents -- not worth interrupting the flow to ask permission. Show a brief note in the output: "Running DataForSEO keyword analysis (~10 cents)..."

For large portfolios (6+ repos): Show the cost estimate and ask before proceeding, because 10+ repos can cost over a dollar:

DataForSEO SEO Pass: [N] repo(s) x ~15 cents = ~[estimated total]
Proceed? [y/n]

Actually STOP and wait for a response. Do NOT continue working while waiting.

If DataForSEO is NOT configured: Do not silently skip it. Encourage setup: "DataForSEO is not configured. SEO data will use GitHub search fallback only. For live keyword research, set it up in 5 minutes: https://dataforseo.com Then run the install script in extensions/dataforseo/."

keyword_suggestions returns volume + difficulty + intent INLINE -- no separate volume or difficulty calls needed.

1. Generate 2-3 seed phrases from: repo name + description + primary language

   SEED QUALITY RULES (critical -- bad seeds waste API calls):
   - Keep seeds SHORT: 2-3 words max. "seo audit tool" not "github seo audit tool"
   - Use CATEGORY-LEVEL terms, not project-specific jargon
   - Think: "what would a developer Google to find this kind of project?"
   - Good seeds: "python web framework", "open source seo tools", "terminal emulator"
   - Bad seeds: "github seo tools", "lightweight WSGI microframework server"

   SEED FALLBACK: If a seed returns zero results, it was too specific.
   Broaden it by removing words. "github seo" → "seo tools" → "open source seo tools".
   Budget: max 4 keyword_suggestions calls total. If all 4 return nothing usable,
   fall back to codebase + GitHub search analysis (no DataForSEO).

2. Call: dataforseo_labs_google_keyword_suggestions (once per seed)
   Params: { "keyword": "python web framework", "location_name": "United States", "language_code": "en", "limit": 30 }
   → Returns ~30 candidates each with volume, difficulty, and intent already included
   → Filter: drop anything under 50/mo volume, flag difficulty under 40 as Sweet Spot
   → NOTE: parameter is "keyword" (singular string), NOT "seed_keywords" (array)
   → NOTE: use "location_name": "United States", NOT "location_code": 2840

3. Call: serp_organic_live_advanced (on best Sweet Spot candidate)
   Params: { "keyword": "python web framework", "location_name": "United States", "language_code": "en", "device": "desktop", "depth": 20 }
   → THE CRITICAL CHECK: scan for "github.com" in results.
   → If github.com in top 10: keyword is GOLD (GitHub Viability = 1.0)
   → If github.com in 11-20: possible (0.5)
   → If no github.com at all: SKIP this keyword, try next candidate

Store the results as SEO context. Format:

## SEO Data (from DataForSEO)

### Keyword Opportunities (by Opportunity Score)
| Keyword | Volume/mo | Difficulty | GitHub in SERP? | Category |
|---------|----------|------------|----------------|----------|
| [term] | X | Y | Yes (#N) | Sweet Spot |
| [term] | X | Y | Yes (#N) | Worth It |

### Placements
- Primary keyword: [term] → H1, description, first paragraph
- Secondary keywords: [terms] → H2 headings
- Topic keywords: [terms] → GitHub topics

### AI Visibility
- ChatGPT mentions: [yes/no]
- Competitors mentioned instead: [list]

Data source: DataForSEO MCP (live, [date])

If DataForSEO is NOT available, note: SEO Data: fallback mode (codebase + GitHub search analysis). Skills will then use their own fallback methods (see github-seo skill).

CACHE: After the SEO pass, write .github-audit/seo-data.json with keyword opportunities, placements, and AI visibility findings.

Cost: ~10-15 cents per repo (2 keyword calls + 1 SERP check). Warn user before portfolio analysis (multiply by repo count).

Step 4: Route to Sub-Skill

Pass intent + repo type + baseline data + SEO data (if available) to the appropriate sub-skill.

Default behavior for bare github <owner/repo> (no sub-command): When the user provides a repo without specifying a sub-skill, run Steps 1-3.5 (intent, baseline, repo type, SEO data), then present a Quick Health Summary:

## Quick Health Summary: owner/repo

**Repo type:** [detected type] | **Intent:** [captured or assumed intent]
**Stars:** X | **License:** MIT | **Last release:** vX.X.X (date)

### Top 3 Recommended Actions (by impact)
1. [Highest impact action] → use `github-[sub-skill]`
2. [Second action] → use `github-[sub-skill]`
3. [Third action] → use `github-[sub-skill]`

### SEO Snapshot (if DataForSEO available)
Primary keyword opportunity: "[keyword]" (X/mo, difficulty Y, GitHub at #Z)

Run `github-audit` for a full 0-100 score, or pick a specialized skill above to start.

This gives the user immediate value and a clear next step, instead of just showing a menu.

For requests explicitly matching a sub-skill (for example, README optimization), route directly to that sub-skill.

The GARE Pattern

Every skill follows Gather, Analyze, Recommend, Execute:

1. Gather -- Collect data before making decisions
2. Analyze -- Compare current state vs. ideal for repo type + intent
3. Recommend -- Present data-backed recommendations with reasoning
4. Execute -- Apply changes with user approval

Every recommendation must cite its source:

• "Based on DataForSEO keyword volume..." (live data)
• "Based on analysis of your codebase..." (repo scan)
• "Based on your repo type (CLI tool)..." (detection)
• "Based on GitHub's indexing rules..." (reference file)
• "Based on audit findings..." (prior audit run)
• "Based on your stated intent..." (user intent)

UX Principles (applies to ALL skills)

Hold the user's hand through manual steps. Many GitHub actions have no API (profile photo upload, social preview, repo settings). When a skill requires manual action, provide:

1. Clickable file links for generated files: file:///[absolute-path]/assets/banner.webp
2. Direct URLs to the exact settings page: https://github.com/{owner}/{repo}/settings -- always substitute the actual owner/repo, never leave placeholders when you know the values
3. Step-by-step instructions numbered and specific: "Go to X, click Y, upload Z"
4. Verification links when possible: "Test your social preview at https://www.opengraph.xyz"

The goal is zero guesswork for the user. If they need to upload a file, show them exactly where the file is AND exactly where to upload it. If they need to change a setting, link them to the exact page. Make the manual parts as close to automated as possible.

Generated image link rule (banners, avatars, social previews): Whenever ANY image is generated or referenced for manual upload, ALWAYS output TWO clickable links:

1. Local: file:///[absolute-path]/image.webp (for immediate access)
2. Remote: https://raw.githubusercontent.com/{owner}/{repo}/main/{path} (after push) Plus the relevant settings/upload URL. Never just mention a relative path like assets/banner.webp without the clickable link. This applies to:

• README banners (github-readme skill)
• Social preview images (github-meta skill)
• Profile avatars (github-empire skill)
• Any other generated image that requires manual upload

Image format pipeline: All AI-generated images (banners, avatars) follow the same flow: request PNG from KIE.ai (lossless source) then convert to WebP (quality 80) for delivery. WebP is ~30% smaller than JPEG at equivalent quality and GitHub renders it natively. See banner-generation.md Image Format Pipeline for details.

Reference Files

Load on-demand as needed -- do NOT load all at startup.

Path resolution: Reference files are installed at github/references/. When a sub-skill says Read github/references/foo.md, use the Read tool with the full path: github/references/foo.md

• references/license-guide.md -- License types, compatibility, fork obligations
• references/readme-framework.md -- README structure, SEO patterns, headings
• references/github-seo-guide.md -- GitHub ranking factors, Google indexing rules
• references/community-files-guide.md -- Standard files, best practices, priority by intent
• references/community-templates.md -- YAML issue forms, PR template, devcontainer, dependabot
• references/banner-generation.md -- KIE.ai GPT Image 2 API, prompt engineering, defaults
• references/releases-guide.md -- Semver, changelog format, badge URLs
• references/repo-type-templates.md -- Per-type defaults for all repo types
• references/shared-data-cache.md -- Cross-skill data persistence schemas and rules

Scoring Methodology

GitHub Health Score (0-100)

Priority Levels

• Critical: Blocks discoverability or creates legal risk (immediate fix)
• High: Significantly impacts professional appearance (fix within 1 week)
• Medium: Optimization opportunity (fix within 1 month)
• Low: Nice to have (backlog)

Standard Operating Procedure (SOP)

The skill suite is designed to be run in a specific order. Each skill builds on the work of the previous one. Do not skip skills or run them out of order unless a category already scores 90+ (in which case, skip it).

The canonical workflow:

github-audit          Step 0: Diagnose (scores 6 categories, generates SOP)
    |
github-legal          Step 1: Foundation (license, compliance, fork obligations)
    |
github-community      Step 2: Infrastructure (templates, CoC, devcontainer)
    |
github-release        Step 3: Versioning (CHANGELOG, badges, catch-up releases)
    |
github-seo            Step 4: Research (keyword data for description + README)
    |
github-meta           Step 5: Settings (description, topics, features -- uses SEO data)
    |
github-readme         Step 6: Capstone (README optimization -- uses everything above)
    |
github-audit          Step 7: Measure (re-audit to verify improvement)

Why this order:

• Legal must come first because every other file references the license
• Community files must exist before releases reference them
• SEO keyword research must happen before meta and readme consume those keywords
• README is last because it references all other files and uses SEO keywords
• The final audit measures the delta and catches anything that slipped through

Each skill ends with a handoff pointing the user to the next step. The user should never finish a skill and wonder "what now?" -- the skill tells them.

Two-phase approach:

Phase 1: Per-Repo Optimization (repeat for each repo)
  github-audit -> github-legal -> github-community -> github-release -> github-seo -> github-meta -> github-readme -> audit

Phase 2: Portfolio Optimization (run once, after all repos are done)
  github-empire -> profile README, cross-linking, topic sync, branding, avatar

Empire operates at the portfolio level and assumes each repo is already in good shape. Running it before the individual repos are optimized means it will make recommendations based on incomplete data. Always finish Phase 1 on all repos first.

Sub-Skills

1. github-audit -- Full repo health audit with 0-100 scoring (Step 0 + Step 7)
2. github-legal -- License, attribution, SECURITY.md, CITATION.cff (Step 1)
3. github-community -- Community health files and templates (Step 2)
4. github-release -- Release strategy, CHANGELOG, badges (Step 3)
5. github-seo -- Keyword research and content optimization (Step 4)
6. github-meta -- Description, topics, settings, social preview (Step 5)
7. github-readme -- README generation and optimization (Step 6)
8. github-empire -- Portfolio strategy, profile README, org profile (after all repos)

Parallel Reviewers

For parallel analysis during audits, use Claude Code subagents or Codex multi-agents with these category assignments:

• github-legal -- Legal compliance scoring
• github-community -- Community health scoring
• github-release -- Release and maintenance scoring
• github-seo -- SEO and discoverability scoring
• github-meta -- Metadata and discovery scoring
• github-readme -- README quality scoring