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, 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
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).
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.
1---
2name: github-profile
3description: >
4 Audits and optimizes GitHub profile pages — profile README, metadata fields, pinned repositories,
5 stats widgets, and contribution visibility. Use this skill whenever the user asks to improve,
6 create, review, or optimize their GitHub profile, or mentions "profile README", "GitHub bio",
7 "pinned repos", "GitHub stats", "contribution graph", or "GitHub presence". Also trigger when
8 someone says things like "make my GitHub look good", "I want a better GitHub profile",
9 "help me stand out on GitHub", "set up my GitHub page", or "optimize my developer profile".
10 Works for both personal profiles and organization profile pages.
11metadata:
12 source: https://skillmd.com/skills/jdevalk/github-profile
13---
14
15# GitHub Profile Optimizer
16
17This 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.
18
19**Code recipes live in `AGENTS.md`** — read it when you need to implement a specific fix. This file has the workflow and audit checklist.
20
21## Workflow
22
231. **Gather profile context** — Understand who this person/org is and what they want to showcase
242. **Audit the current profile** — Score every element of the profile's public presence
253. **Generate the profile README** — Write a polished, scannable README.md
264. **Recommend metadata and configuration** — Advise on bio, pinned repos, settings, and widgets
275. **Verify** — Confirm rendering, badge URLs, and summarize next steps
28
29---
30
31## Phase 0: Gather Context
32
33### Determine profile type
34
35Ask the user (if not obvious): is this a **personal profile** or an **organization profile**? The mechanics differ significantly:
36
37| Feature | Personal profile | Organization profile |
38| --- | --- | --- |
39| README location | `username/username/README.md` | `.github/profile/README.md` |
40| Visibility options | Public only | Public + member-only (via `.github-private` repo) |
41| Pinned repos | Up to 6 | Up to 6 public + 6 member-only |
42| Contribution graph | Yes | No |
43| Achievements | Yes | No |
44
45### Collect information
46
47Gather 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).
48
49If `gh` is available (`gh auth status`), pull automatically:
50
51- `gh api user` — name, bio, company, location, blog, twitter
52- `gh api users/{username}/repos?sort=stars&per_page=10` — top repos for pin recommendations
53- `gh repo view {username}/{username} --json name 2>/dev/null` — check if magic repo exists
54
55---
56
57## Phase 1: Audit
58
59If 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):
60
61### Profile README (x/10)
62
63- **Exists?** No `username/username` repo with README.md is the biggest miss.
64- **Structure** — Ideal flow: greeting/identity → current work → tech stack (badges) → GitHub stats → featured projects → social links → personal touch.
65- **Length** — 400-800 words. Under 200 feels thin; over 2,000 clutters.
66- **Scannability** — Gist in 10 seconds? Use `<details>` for collapsible sections.
67- **Freshness** — Dynamic content still updating? GitHub stops cron Actions after 60 days of repo inactivity.
68
69### Profile Metadata (x/10)
70
71Every empty field is a missed opportunity:
72
73- **Photo** — clear headshot, consistent across platforms?
74- **Bio** — filled in (160 char limit), states role + primary tech + distinguishing trait?
75- **Company** — linked with `@` prefix? **Location, Website** — filled in?
76- **Social accounts** — Twitter/X, LinkedIn linked? Cross-linking builds trust.
77- **Pronouns** — signals inclusivity. **Status** — shows current work or availability?
78
79### Pinned Repositories (x/10)
80
81Up to 6 repos (including contributed-to repos):
82
83- All 6 slots used? Descriptions filled in? Variety across technologies?
84- Prioritize repos with stars (social proof) that align with career/business goals.
85- Each pinned repo should have a polished README (github-repo skill applies here).
86
87### Contribution Activity (x/10)
88
89- **Graph** — reasonably active? Completely empty raises questions.
90- **Private contributions** — "Include private contributions" enabled in settings?
91- **Achievements** — Starstruck, Pull Shark, Arctic Code Vault Contributor add credibility.
92
93---
94
95## Phase 2: Generate the Profile README
96
97Based on the audit (or from scratch), produce the profile README. **Read `AGENTS.md` for detailed recipes.**
98
99The profile README should be scannable, personal, and purposeful — every section should serve the person's goals. Adapt tone and structure to the audience.
100
101`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.
102
103---
104
105## Phase 2.5: Metadata and readability pass
106
1071. **`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).
1082. **`readability-check` skill** — run on the profile README body. Profile READMEs are skimmed; one passive or long sentence stands out.
109
110Apply 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).
111
112---
113
114## Phase 3: Recommendations
115
116### Metadata to update
117
118Be specific: "Set your bio to: [text, under 160 chars]", "Add these topics to your top repos: [list]", "Set your status to: [suggestion]".
119
120### Pinned repository strategy
121
122Recommend 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).
123
124---
125
126## Phase 4: Verify
127
128- Confirm the README renders correctly (check markdown syntax, badge URLs, image links)
129- Check that all shields.io badge URLs are valid (correct logo names, hex colors)
130- Verify stats widget URLs use the correct username
131- If generating locally, remind the user to create the magic repo (`username/username`) if it doesn't exist, and push the README there
132- Summarize next steps: what to commit/push, what to change in GitHub settings manually
133
134---
135
136## Output format
137
138Score 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).
139
140---
141
142## Key principles
143
144- **Scannable over comprehensive.** A profile is skimmed in 10 seconds. Cut anything that doesn't earn its space.
145- **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.
146- **Every field filled.** Empty metadata fields, missing pinned repos, and blank descriptions are missed opportunities.
147- **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`.
148- **Cross-link everything.** GitHub, LinkedIn, Twitter/X, personal site — each profile should point to the others.