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
- Gather profile context — Understand who this person/org is and what they want to showcase
- Audit the current profile — Score every element of the profile's public presence
- Generate the profile README — Write a polished, scannable README.md
- Recommend metadata and configuration — Advise on bio, pinned repos, settings, and widgets
- 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:
| Feature | Personal profile | Organization profile |
|---|---|---|
| README location | username/username/README.md | .github/profile/README.md |
| Visibility options | Public only | Public + member-only (via .github-private repo) |
| Pinned repos | Up to 6 | Up to 6 public + 6 member-only |
| Contribution graph | Yes | No |
| Achievements | Yes | No |
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, twittergh api users/{username}/repos?sort=stars&per_page=10— top repos for pin recommendationsgh 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/usernamerepo 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
metadata-checkskill — 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).readability-checkskill — 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; seeAGENTS.md. - Cross-link everything. GitHub, LinkedIn, Twitter/X, personal site — each profile should point to the others.
