github-readme
starsforks
How to install github-readme?
avalonreset/legends-github/github-readme
$npx -y skills add avalonreset/legends-github --skill github-readmeGenerate or optimize GitHub README files with SEO-optimized structure, badges, and 21:9 banner image generation via GPT Image 2.
SKILL.md
| 1 | # GitHub README -- Generation and Optimization |
| 2 | |
| 3 | ## Headless Contract |
| 4 | |
| 5 | For deterministic local preview/write flows, use: |
| 6 | |
| 7 | ```bash |
| 8 | python3 scripts/run_headless.py readme --path /path/to/repo |
| 9 | python3 scripts/run_headless.py readme --path /path/to/repo --generate-assets |
| 10 | python3 scripts/run_headless.py readme --path /path/to/repo --write |
| 11 | ``` |
| 12 | |
| 13 | `readme` defaults to preview mode. It writes `.github-audit/readme-data.json` |
| 14 | plus `README-REPORT.md`, `README-PREVIEW.md`, and `README-SUMMARY.json`. |
| 15 | `--write` is the explicit approval gate for rewriting `README.md`. |
| 16 | `--generate-assets` reuses an existing banner asset when present, otherwise it |
| 17 | can generate a KIE-backed banner plus `assets/social-preview.jpg` and records |
| 18 | local/raw/settings links in the cache and report artifacts. |
| 19 | |
| 20 | ## Process (GARE Pattern) |
| 21 | |
| 22 | ### 1. Gather |
| 23 | |
| 24 | **Step 0 -- Check shared data cache:** |
| 25 | Before gathering, check `.github-audit/` for cached data from other skills. |
| 26 | Reference: `github/references/shared-data-cache.md` for schemas. |
| 27 | |
| 28 | - `seo-data.json` (**REQUIRED -- do NOT skip**) -- primary keyword, secondary keywords, PAA |
| 29 | questions, AI visibility. **If this cache file is missing, you MUST gather SEO data |
| 30 | before proceeding.** Check if DataForSEO MCP tools are available (search for |
| 31 | `dataforseo_labs_google_keyword_suggestions`). If available, run the keyword research |
| 32 | inline: generate 2 seed keywords from repo description → call keyword_suggestions for |
| 33 | each → filter by volume/difficulty/relevance → call serp_organic_live_advanced on the |
| 34 | best candidate to verify GitHub repos can rank for it. This costs ~20-30 cents and is |
| 35 | NON-NEGOTIABLE -- a README without data-backed keywords is a failed deliverable. |
| 36 | If DataForSEO MCP is genuinely not configured (tools not found), THEN and ONLY THEN |
| 37 | fall back to codebase-derived keywords and mark SEO as "unverified." |
| 38 | - `repo-context.json` (optional) -- repo type, intent, language, metadata. If missing, |
| 39 | gather yourself via `gh repo view`. |
| 40 | - `legal-data.json` (optional) -- license type for badge selection. If missing, just |
| 41 | check LICENSE file directly. |
| 42 | - `audit-data.json` (optional) -- README quality findings from prior audit. If present, |
| 43 | use to prioritize which sections need the most improvement. |
| 44 | |
| 45 | - **Codebase scan:** What does this project actually do? |
| 46 | - Read package.json/setup.py/Cargo.toml for description, scripts, dependencies |
| 47 | - Check for existing docs, examples, config files |
| 48 | - Identify main entry point and key exports/commands |
| 49 | - **Existing README:** Read current README.md (if any) |
| 50 | - Also check for README.rst (reStructuredText) -- some Python/Sphinx projects use it |
| 51 | - If both exist, README.md takes priority (GitHub renders it on the landing page) |
| 52 | - Assess structure, headings, content depth |
| 53 | - Identify what's missing vs. ideal for this repo type |
| 54 | - **SEO data:** Use keyword opportunity data from the orchestrator's SEO data pass, |
| 55 | or run github-seo inline if running standalone. |
| 56 | - If SEO data block was provided (from Step 3.5 of orchestrator), use it directly: |
| 57 | - Primary keyword (Sweet Spot category) → goes in H1 tagline and first paragraph |
| 58 | - Secondary keywords (Worth It category) → go in H2 headings where natural |
| 59 | - "Skip" keywords → do NOT target in H1/H2, but if a Skip keyword appears |
| 60 | naturally in body text and is semantically relevant, that's fine -- just don't |
| 61 | optimize headings or structure around it. The distinction is between "targeting" |
| 62 | (building structure around a keyword) and "mentioning" (natural use in prose). |
| 63 | - AI citation status → if not cited, add stronger "X is a Y that does Z" definition |
| 64 | - If running standalone via `github-readme`, gather SEO data yourself: |
| 65 | - If DataForSEO MCP available: run the Keyword Opportunity Framework from |
| 66 | github-seo skill (seed generation → keyword expansion → volume → difficulty → |
| 67 | SERP viability check). The SERP check is critical -- only target keywords where |
| 68 | GitHub repos actually appear in Google results. |
| 69 | - If DataForSEO not available: analyze codebase, check competitor repos via |
| 70 | `gh search repos`, apply patterns from github-seo-guide.md |
| 71 | - In all cases, produce: primary keyword, secondary keywords, recommended H1, H2 headings |
| 72 | - Every keyword placed in the README must have a justification (volume data, competitor |
| 73 | analysis, or codebase relevance) |
| 74 | - **Legal data:** Check LICENSE type for License section |
| 75 | - **Audit data:** If a prior `github-audit` run exists, use its README quality findings |
| 76 | - **Intent + repo type:** From orchestrator context |
| 77 | - **Banner status:** Does the repo already have a banner image? Check for `assets/banner.webp`, `assets/banner.jpg`, `assets/banner.png`, or any image referenced at the top of README |
| 78 | |
| 79 | ### 2. Analyze |
| 80 | |
| 81 | Reference: Read `github/references/readme-framework.md` for structure pat |
People who liked this also viewed
6 picksType
- caveman-commitUltra-compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. UsSkillsJul 2026
- git-guardrails-claude-codeSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- setup-pre-commitSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- resolving-merge-conflictsSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- using-git-worktreesUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackSkillsJul 2026
- finishing-a-development-branchUse when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanupSkillsJul 2026
