GitHub Profile Optimizer

This skill audits a GitHub profile and generates an optimized profile README along with recommendations for metadata, pinned repositories, and stats widgets. A strong GitHub profile is a developer's storefront — it shapes perception before anyone reads a line of code.

Code recipes live in AGENTS.md — read it when you need to implement a specific fix. This file has the workflow and audit checklist.

Workflow

1. Gather profile context — Understand who this person/org is and what they want to showcase
2. Audit the current profile — Score every element of the profile's public presence
3. Generate the profile README — Write a polished, scannable README.md
4. Recommend metadata and configuration — Advise on bio, pinned repos, settings, and widgets
5. Verify — Confirm rendering, badge URLs, and summarize next steps

---

Phase 0: Gather Context

Determine profile type

Ask the user (if not obvious): is this a personal profile or an organization profile? The mechanics differ significantly:

Collect information

Gather before writing: username, current role/company, primary technologies, what they want to showcase, tone (professional/casual/creative/minimal), and target audience (recruiters/collaborators/investors/OSS community).

If gh is available (gh auth status), pull automatically:

• gh api user — name, bio, company, location, blog, twitter
• gh api users/{username}/repos?sort=stars&per_page=10 — top repos for pin recommendations
• gh repo view {username}/{username} --json name 2>/dev/null — check if magic repo exists

---

Phase 1: Audit

If the user has an existing profile, audit it. If they're starting fresh, skip to Phase 2. Score four categories (each x/10, total x/40):

Profile README (x/10)

• Exists? No username/username repo with README.md is the biggest miss.
• Structure — Ideal flow: greeting/identity → current work → tech stack (badges) → GitHub stats → featured projects → social links → personal touch.
• Length — 400-800 words. Under 200 feels thin; over 2,000 clutters.
• Scannability — Gist in 10 seconds? Use <details> for collapsible sections.
• Freshness — Dynamic content still updating? GitHub stops cron Actions after 60 days of repo inactivity.

Profile Metadata (x/10)

Every empty field is a missed opportunity:

• Photo — clear headshot, consistent across platforms?
• Bio — filled in (160 char limit), states role + primary tech + distinguishing trait?
• Company — linked with @ prefix? Location, Website — filled in?
• Social accounts — Twitter/X, LinkedIn linked? Cross-linking builds trust.
• Pronouns — signals inclusivity. Status — shows current work or availability?

Pinned Repositories (x/10)

Up to 6 repos (including contributed-to repos):

• All 6 slots used? Descriptions filled in? Variety across technologies?
• Prioritize repos with stars (social proof) that align with career/business goals.
• Each pinned repo should have a polished README (github-repo skill applies here).

Contribution Activity (x/10)

• Graph — reasonably active? Completely empty raises questions.
• Private contributions — "Include private contributions" enabled in settings?
• Achievements — Starstruck, Pull Shark, Arctic Code Vault Contributor add credibility.

---

Phase 2: Generate the Profile README

Based on the audit (or from scratch), produce the profile README. Read AGENTS.md for detailed recipes.

The profile README should be scannable, personal, and purposeful — every section should serve the person's goals. Adapt tone and structure to the audience.

AGENTS.md sections: Personal profile README template, Stats widgets, Badges for tech stack and social links, Dynamic auto-updating content, Organization profile README, Profile generators.

---

Phase 2.5: Metadata and readability pass

1. metadata-check skill — run on the GitHub bio (160 chars) and any pinned repo descriptions you rewrote. Front-loading, concreteness, active voice, truncation fit (GitHub shows ~100 chars in profile cards).
2. readability-check skill — run on the profile README body. Profile READMEs are skimmed; one passive or long sentence stands out.

Apply fixes directly. Focus on: (1) bio / opening README line (disproportionate weight); (2) first sentence of each section (skimming entry point); (3) passive voice (flat in first-person content).

---

Phase 3: Recommendations

Metadata to update

Be specific: "Set your bio to: [text, under 160 chars]", "Add these topics to your top repos: [list]", "Set your status to: [suggestion]".

Pinned repository strategy

Recommend which 6 repos to pin and why — variety across technologies, star count (social proof), README quality, alignment with goals. If pinned repos have weak READMEs, suggest improving those first (github-repo skill).

---

Phase 4: Verify

• Confirm the README renders correctly (check markdown syntax, badge URLs, image links)
• Check that all shields.io badge URLs are valid (correct logo names, hex colors)
• Verify stats widget URLs use the correct username
• If generating locally, remind the user to create the magic repo (username/username) if it doesn't exist, and push the README there
• Summarize next steps: what to commit/push, what to change in GitHub settings manually

---

Output format

Score table (4 categories, each x/10, total x/40) → Findings grouped by category → Files generated or changed → Next steps (settings changes, repos to pin, manual GitHub config).

---

Key principles

• Scannable over comprehensive. A profile is skimmed in 10 seconds. Cut anything that doesn't earn its space.
• Personality over template. Adapt tone, structure, and content to the person's goals and audience. A creative developer and a startup founder need different profiles.
• Every field filled. Empty metadata fields, missing pinned repos, and blank descriptions are missed opportunities.
• Dynamic where it adds value. A stats image (via lowlighter/metrics) and an optional auto-updating blog feed keep a profile fresh — one of each is usually plenty. Avoid third-party-hosted widgets that 502 unpredictably; see AGENTS.md.
• Cross-link everything. GitHub, LinkedIn, Twitter/X, personal site — each profile should point to the others.