# Github > GitHub repository optimization suite. Orchestrates sub-skills to audit and professionalize repos across README, legal, metadata, SEO, community, and releases. - **Type:** Skill - **Install:** `agentstack add skill-avalonreset-legends-github-github` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [avalonreset](https://agentstack.voostack.com/s/avalonreset) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [avalonreset](https://github.com/avalonreset) - **Source:** https://github.com/avalonreset/legends-github/tree/main/github ## Install ```sh agentstack add skill-avalonreset-legends-github-github ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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, CODE_OF_CONDUCT, 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: ```bash 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: ```bash 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:** ```bash 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, 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: ```bash 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. ## 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:** yes - **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-avalonreset-legends-github-github - Seller: https://agentstack.voostack.com/s/avalonreset - 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%.