github-repo

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub Repository Optimizer

This skill audits a GitHub repository against best practices and generates or improves the files that make a repo look professional, welcoming, and well-maintained. It works with live repos (via `gh` CLI), local git directories, or files the user provides.

## Workflow

1. **Gather repo context** — Determine what we're working with and collect information
2. **Run the audit** — Score every aspect of the repo's public-facing quality
3. **Generate or improve files** — Produce the files that are missing or need work
4. **Verify** — Confirm the outputs are correct and complete

---

## Phase 0: Gather Context

Figure out what you're working with. Try these sources in order:

### If in a local git directory

Check the current working directory for a `.git` folder. If present:

- Read the existing README.md, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, LICENSE, CHANGELOG.md
- Check `.github/` for issue templates, PR templates, workflows, CODEOWNERS, FUNDING.yml, dependabot.yml
- Run `git remote -v` to identify the GitHub remote
- Run `git branch -a` to assess branch hygiene
- Run `git tag --list` to check release tagging

### If `gh` CLI is available and authenticated

Try `gh auth status` first. If authenticated:

- `gh repo view --json name,description,url,homepageUrl,repositoryTopics,licenseInfo,isArchived,defaultBranchRef,stargazerCount,forkCount,hasIssuesEnabled,hasWikiEnabled` — repo metadata
- `gh api repos/{owner}/{repo}/community/profile` — community health score
- `gh api repos/{owner}/{repo}/branches` — branch list for hygiene check
- `gh release list --limit 5` — recent releases
- `gh api repos/{owner}/{repo}/contents/.github` — check for templates and config

If `gh` isn't available or not authenticated, that's fine — work with what you have. Ask the user to provide files or a repo URL only if you have nothing to go on.

### Key information to collect

Before auditing, make sure you understand:

- What the project does (language, framework, purpose)
- Who the audience is (developers, end users, both)
- Whether it's an org repo or personal repo
- Whether it's a library, application, CLI tool, or something else

This context shapes every recommendation. A React component library needs different README sections than a CLI tool or a WordPress plugin.

---

## Phase 1: Audit

Score the repository across these categories. For each, give a score out of 10 and write 2-4 specific, actionable findings that reference the actual content (never be generic).

### Score Table

Present this at the top of the audit:

```text
Category                        Score
─────────────────────────────────────
README Quality                  x/10
Repository Metadata             x/10
Community Health Files          x/10
Issue & PR Templates            x/10
CI/CD & Automation              x/10
Releases & Branch Hygiene       x/10
─────────────────────────────────────
Overall                         x/60
```

**Score ranges:**

- **50–60** — Excellent. Minor polish only.
- **35–49** — Good foundation, real gaps to fill. Optimization will make a visible difference.
- **20–34** — Significant issues. Multiple files need creation or rewriting.
- **0–19** — Bare bones. Treat this as building the repo's public presence from scratch.

### What to evaluate per category

#### README Quality (x/10)

The README is the repo's landing page and the single highest-impact file.

**Structure** — Does it follow a logical flow? The ideal order for a repo README:

1. Logo/project name (centered, for brand recognition)
2. Badge row (build status, coverage, license, version, downloads — aim for 5-10, not more)
3. One-liner description (a compelling elevator pitch, not a generic statement)
4. Visual demo (screenshot, GIF, or terminal recording — this dramatically increases engagement)
5. Quick start (3 steps or fewer to get running)
6. Table of contents (if README exceeds ~200 lines)
7. Installation (step-by-step with code blocks and language-appropriate syntax highlighting)
8. Usage examples (real code showing common use cases, not toy examples)
9. Configuration (environment variables, config files, options)
10. Contributing (brief section linking to CONTRIBUTING.md)
11. License (license type with link to full text)

**Content quality** — Is the description clear about what the project does and who it's for? Are code examples copy-pasteable and correct? Is there a visual (screenshot/GIF)?

**Technical details** — Is syntax highlighting used in code blocks? Are links working? Is the length reasonable (under 500 lines, with detailed docs in `/docs` if needed)?

#### Repository Metadata (x/10)

The "About" section fields have outsized impact on discoverability.

- **Repository name** — Is it descriptive and keyword-rich? `react-calendar` is far better than `my-widget`. Lowercase with hyphens.
- **Description** — Is it filled in? Is it keyword-rich and concise? An empty description is a red flag.
- **Topics/tags** — Are there at least 6? Mix of technology stack, domain, and purpose. Up to 20 allowed. Don't duplicate the auto-detected primary language.
- **Website URL** — Is there a documentation site, homepage, or live demo linked?
- **Social preview image** — Is a custom image set (1280×640px, 2:1 ratio)? Without one, shared links on social media show a generic avatar. Tools like GitHub Socialify or Canva can generate these.

#### Community Health Files (x/10)

These are the baseline for any serious repository.

- **CONTRIBUTING.md** — Does it exist? Does it explain how to contribute, code style expectations, and the PR process? Does it mention issue/PR templates?

From courtneyr-dev/agent-skills, MIT.

More from courtneyr-dev/agent-skills