github-profile-optimizer

---
name: github-profile-optimizer
description: One-stop GitHub profile optimization. Show the user real profile examples (two per style), let them pick style, language, audience and an optional credit line in one question window, then do everything else automatically - read public repos, PRs and a local resume, write a Profile README (the username/username repo) in the chosen layout, a short bio and a contribution snake, self-check links and images, guide gh authorization and publish. Use when the user says "optimize / beautify / make my GitHub profile", "my profile looks bad", "write a profile README", "GitHub homepage like the pros", "update my GitHub bio", or the Chinese equivalents (优化/美化 GitHub 主页, 写 profile README, 像大佬那样的 GitHub 首页, 改 GitHub 简介), even if README is never mentioned. Not for writing a README for a specific project, and not for finding open-source contributions.
---

# GitHub Profile Optimizer

The right side of a GitHub profile page is the README.md of the repo `<login>/<login>`; the left side is the avatar and bio. All the fancy effects are images from services referenced in that README, or images generated by GitHub Actions.

Most users are beginners and don't know what a profile can look like. Don't ask abstract questions like "what style do you want". Show real profiles and let them pick. Read everything you can yourself; ask only what you can't decide, and give options when you ask.

The user takes part in only three places: answer four questions in one window (style, language, audience, credit line) → authorize (which means agreeing to publish) → say whether they're satisfied. After they say they're satisfied, they get one optional, skippable question about starring this project (step 7).

## Conversation language

Talk to the user in the language they write in: questions, options, explanations and the final report. A user writing in Chinese gets everything in Chinese. This is separate from the README language, which the user picks in step 1.

## Workflow

### 1. Ask all four questions at once

Ask the four questions in a single question window (in Claude Code, one AskUserQuestion call with 4 questions). Without a question tool, list four numbered questions in one reply so the user can answer in one message. Authorization comes later, in step 4.

1. **Style**: the options are the 4 styles in [references/showcase.md](references/showcase.md). Put the full URLs of both example profiles in each option's description so the user can copy and open them. If the user wants to follow another profile, they can paste its link under "Other".
2. **README language**: Mixed (English headings, Chinese body) / English only / Chinese only. If the user's repo descriptions are mostly Chinese, put Mixed first and mark it recommended; otherwise put English only first. For a user writing in another language, offer English / that language / mixed instead of Chinese.
3. **Audience**: who will mainly read the profile? Technical peers (default, mark recommended) / Recruiters / Open-source community.
4. **Credit line**: this tool is free and open source; would they add one small line at the very bottom of the profile to help promote it? Options: Add / Don't add.

Put the example links in two places: as clickable full URLs in the reply text before the window (one per line), and in the option descriptions for easy copying.

**Ask all four questions every time.** Don't skip any because the user picked their current profile, had earlier settings, or because of commit history.

Username: if `gh auth status` shows a login, use it. Otherwise the window is full, so ask for the GitHub username in the reply text.

If the user agrees to the credit line, add this at the end of the README:

```html
<p align="center"><sub>Made with <a href="https://github.com/mizane446/github-profile-optimizer">github-profile-optimizer</a></sub></p>
```

### 2. Read data

```bash
gh api users/<login>
gh repo list <login> --limit 100 --json name,description,primaryLanguage,stargazerCount,isFork,isPrivate
gh search prs --author <login> --limit 30 --json repository,title,state,url
gh api repos/<example>/<example>/readme -H "Accept: application/vnd.github.raw"   # source of the chosen example, returned as raw text
```

- No gh installed: read data with `curl https://api.github.com/...` (same paths) and install gh before publishing (see step 4).
- Read the first few dozen lines of each candidate project's README to learn what it does and what it uses.
- External PRs count only if they're in other people's repos. Note open / merged.
- If the user gave a resume path, or the working directory has a personal profile file (such as `关于我.md`, `about-me.md` or a resume), read it to fill in the technical direction, and tell the user which file you're reading first. The profile is public: don't copy phone, email, school, city or other personal details from the resume. Include them only if the user explicitly asks in the conversation.
- If there isn't enough to write decent content (fewer than 2 public projects, no clear technical direction), ask the user one question: which projects to highlight and what direction they work in.

### 3. Generate

Follow the example's layout: same section order, formatting and image services. Layout details and image service URLs are in [references/services.md](references/services.md).

- **Replace sections that don't fit**: a section the example has but the user has no data for (releases, blog, lots of stats) becomes content the user does have, in the same position (representative projects, open-source PRs, tech stack).
- **User picked their own current profile**: keep the layout and only update stale content (PRs merged, new projects). Language and credit line follow the step 1 answers. If nothing changed, tell the user no update is needed and stop.
- **Content rules**: write for the audience chosen in step 1. Technical peers: what was built and how; no "job seeking" or "internship". Recruiters: the tagline and projects highlight the target role, it's fine to say what opportunities they're looking for, and projects state what the user personally did. Open-source community: highlight open-source PRs, maintained projects and how to collaborate. Personal details (school, city, email) only if the user asked for them in the conversation. Pick 3-6 representative projects that are public, not forks, and match the main direction. The tagline is one sentence and goes in the README.
- **Bio is written separately**: 3-5 keywords separated by " · ", fitting on one line (about 60 characters), for example `Building LLM Agents · Multi-Agent · RAG · AI pipelines`. Don't put the tagline sentence in the bio; the left column is narrow and a long sentence wraps into several lines.
- **Only facts with a source**: numbers and experience must come from repos, PRs or the resume. An open PR is "in review", only a merged PR is "merged". Private repos never appear.
- Don't copy the example's text, images or personal content.

Output goes to `<working dir>/github-profile/`: `README.md` and `bio.txt`. If that folder already exists, first move the old files into `archive/` inside it (file names with the date), then generate fresh from the chosen example; don't edit the old README. Only when the user picked their own current profile do you update the old content. When using the snake, copy [assets/snake.yml](assets/snake.yml) to `.github/workflows/snake.yml`. The working directory defaults to the user's code projects directory.

Self-check before publishing: every external image in the README returns 200 (for example `curl -s -o /dev/null -w "%{http_code}" <url>`; in Windows PowerShell use `curl.exe` and `-o NUL`). Skip the snake image, which only exists after publishing. Every repo and PR link exists.

### 4. Authorization is confirmation

In the reply that ends the turn, state what will happen, then give the authorization steps:

> Next: create (or update) the public repo `<login>/<login>`, change the bio to "<bio>", and turn on the snake that updates daily. The current online README is backed up first, so you can roll back if you don't like it.

- No gh: Windows `winget install --id GitHub.cli`, macOS `brew install gh`, others see https://cli.github.com . Reopen the terminal after installing.
- Run the auth command in the background with output written to a file, and read the device code from the file after a few seconds. The command must not wait for keyboard input: in bash append `< /dev/null`, in PowerShell prefix `$null |`.
  - Not logged in: `gh auth login -h github.com -p https -w -s user,workflow`
  - Logged in but scopes lack `user` or `workflow`: `gh auth refresh -h github.com -s user,workflow`
- Tell the user: open https://github.com/login/device → enter code `XXXX-XXXX` → click Authorize. Publishing starts once they've authorized.
- Scopes already sufficient: skip authorization and ask "Publish now?" instead.

Dry run mode (the user says "generate only, don't publish" or "dry run") ends before this step and reports the output paths.

### 5. Publish

```bash
cd <working dir>/github-profile
# repo already exists: gh repo clone <login>/<login> here first, and save the old README locally as archive/README-<date>.md
git add README.md .github/workflows/snake.yml
git commit -m "Update profile README"
gh repo create <login>/<login> --public --source . --push    # if the repo exists, git push
gh api -X PATCH user -f bio="<bio>"
gh workflow run snake.yml -R <login>/<login>
```

### 6. Wrap up

- Give `https://github.com/<login>` and say what was done. The snake shows up after its workflow finishes (about 1 minute).
- Pinned repos have no API. Tell the user to set them by hand: Popular repositories → Customize your pins (top right) → check the representative projects.
- Ask whether they're satisfied (same question style as step 1): Satisfied / Simpler / Different style / Roll back. For changes, edit and push again. To roll back, push the backed-up README and restore the old bio.
- If they pick Satisfied, continue to step 7. For any other answer, skip step 7.

### 7. Optional star (only after the user says Satisfied)

Reach this step only if the user answered "Satisfied" in step 6 and the profile was actually published. Skip it on dry runs, on Simpler / Different style / Roll back, and when the user's login is `mizane446`.

Check first whether the repo is already starred:

```bash
gh api /user/starred/mizane446/github-profile-optimizer --silent
```

Exit code 0 means already starred: skip this step. A 404 / non-zero exit just means "not starred yet" and is normal, not an error to report. If this check itself is unclear or fails for any other reason, don't investigate; just continue to the question below.

Ask once, in one short line, in the same question style as step 1 (Yes, star it / No thanks), in the user's language:

> Glad it worked. This tool is free and open source. Want me to star github-profile-optimizer for you?

Rules:
- Only on an explicit yes, run `gh api -X PUT /user/starred/mizane446/github-profile-optimizer`, then confirm in one line.
- On "No" or no answer: say nothing more and never ask again in this session.
- If the command fails (missing permission, network, no gh), don't retry or show the raw error. Just give https://github.com/mizane446/github-profile-optimizer and say they can star it by hand if they like.
- Never star without an explicit yes, and never make starring a condition for anything else. Authorization given in step 4 covers publishing the profile only, not starring.

## UI notes

- Links inside question tools (like Claude Code's AskUserQuestion) aren't clickable, so also put them in the reply text. Put the device code in the reply that ends the turn.
- Write full `https://...` links, one per line.