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

| Entry point | What it does | |---------|-------------| | github-audit | Full repo health audit with 0-100 scoring | | github-audit with remote target | Audit a specific remote repo | | github-empire or portfolio audit flow | Audit an entire portfolio | | github-readme | Generate or optimize README | | github-legal | License, SECURITY.md, CITATION.cff, fork compliance | | github-meta | Description, topics, settings, social preview | | github-seo | Keyword research and content optimization strategy | | github-community | Templates, CONTRIBUTING, CODEOFCONDUCT, devcontainer | | github-release | CHANGELOG, badges, versioning, release strategy | | github-empire | Multi-repo portfolio strategy, profile README | | extensions/dataforseo | Live keyword/SERP data (requires DataForSEO account) |

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

| Key | Required By | Purpose | |-----|------------|---------| | KIE_API_KEY | github-readme banner generation | KIE.ai image generation | | DataForSEO credentials | SEO data pass across github-seo, github-meta, github-readme, github-empire | Configured via MCP server, not .env |

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/-/GITHUB-AUDIT-REPORT.md
• .github-audit/output/-/ACTION-PLAN.md
• .github-audit/output/-/SUMMARY.json
• .github-audit/output/-/SEO-REPORT.md
• .github-audit/output/-/SEO-SUMMARY.json
• .github-audit/output/-/LEGAL-REPORT.md
• .github-audit/output/-/LEGAL-PLAN.md
• .github-audit/output/-/LEGAL-SUMMARY.json
• .github-audit/output/-/COMMUNITY-REPORT.md
• .github-audit/output/-/COMMUNITY-PLAN.md
• .github-audit/output/-/COMMUNITY-SUMMARY.json
• .github-audit/output/-/META-REPORT.md
• .github-audit/output/-/META-SUMMARY.json
• .github-audit/output/-/README-REPORT.md
• .github-audit/output/-/README-PREVIEW.md
• .github-audit/output/-/README-SUMMARY.json
• .github-audit/output/-/RELEASE-REPORT.md
• .github-audit/output/-/RELEASE-PROPOSAL.md
• .github-audit/output/-/RELEASE-SUMMARY.json
• .github-audit/output/-/EMPIRE-REPORT.md
• .github-audit/output/-/EMPIRE-BLUEPRINT.md
• .github-audit/output/-/PROFILE-README-DRAFT.md
• .github-audit/output/-/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:

| Intent | Optimization Priorities | |--------|------------------------| | Open Source Community | README (welcoming), community files (critical), topics (broad), SEO (discovery) | | Professional Portfolio | README (impressive), badges (social proof), branding (consistent), pinned repos | | Business / Brand | SEO (aggressive keywords), description (value prop), Pages, cross-linking | | Internal to Public | Legal (thorough), SECURITY.md (critical), README (docs-heavy), CITATION.cff | | Academic / Research | CITATION.cff (required), README (methodology), license (permissive), releases | | Hobby / Learning | README (authentic), legal (simple MIT), community (lightweight), SEO (lower priority) |

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, CODEOFCONDUCT.md, .github/ISSUETEMPLATE/, .github/PULLREQUEST_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

| Type | Signals | |------|---------| | Library/Package | package.json, setup.py, Cargo.toml, go.mod, pyproject.toml | | CLI Tool | bin/, "usage:", commander, yargs, clap, argparse | | Framework | middleware, routing, plugins, "getting started" | | API/Service | /api, swagger, OpenAPI, endpoints | | Application | docker-compose, Dockerfile, deployment configs | | Skill/Plugin | SKILL.md, AGENTS.md, extension pattern | | Documentation | mkdocs.yml, docusaurus.config.js, mostly .md files |

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_

…

## Source & license

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

- **Author:** [avalonreset](https://github.com/avalonreset)
- **Source:** [avalonreset/legends-github](https://github.com/avalonreset/legends-github)
- **License:** MIT

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