Github Polish

github-polish

Give a public repo a clean, professional presentation — sharp metadata and a README that frames the work as a worked example, not an abandoned experiment.

The job is mostly autonomous: survey, print one short plan, then do every CLI-doable thing in one pass without per-step approval. Only two things come back to the user: the actions GitHub gates behind the web UI, and any asset needing a real-world capture (you write the walkthrough, never fake it).

Scope of this version. The default path is the portable, gh-only core: metadata, README, LICENSE, and an honest CLI/UI handback — everything here runs with nothing but an authenticated gh, and can't break in your environment. Branded social cards / banners / diagrams are an optional rendering add-on (Playwright + a brand spec; see SETUP.md and render/); when it's installed, step d below activates. When it isn't, the core is complete on its own and the handback simply tells the user how to add a social preview by hand.

Invocation

/github-polish <arg>

• <repo> → <your-gh-login>/<repo> (owner resolved via gh api user --jq .login). <owner>/<repo> → explicit. A full URL → parse owner/repo from it. . → the repo in cwd (use it, don't re-clone).
• --dry-run (or "just survey" / "show me the plan first") → SURVEY + plan, then STOP. No edits, commits, or pushes. The first real run on any repo should be a dry run.

Hard rules — the integrity of a public, named asset. Internalize the why.

Violating any one damages a public, named asset — the gap surfaces eventually, and that's worse than a plain repo.

1. Honesty over polish. Never fabricate a usage screenshot, invent a metric, or imply a capability the repo lacks. A repo that oversells gets found out eventually. If the honest move is a real capture you can't do, write a capture walkthrough for the UI todo list instead.
2. No private data in public assets. Placeholder data only (Company A–I, generic roles, round-number stats). Scrub real names, paths, emails, keys, internal URLs before anything is committed. When in doubt, genericize.
   • Sanitisation grep (mandatory, pre-commit — never skip). Keep a per-repo pattern of the private signals this repo must never leak, and run it over the working tree before any commit or push, failing closed on any hit — a match blocks the commit until scrubbed:

     git grep -inE '<your private-signal pattern>' -- . ':!*.png'
     

     Zero hits is the only pass. Build the pattern from what would actually harm you if a reader found it — personal identifiers, nationality- or health-adjacent signals, self-assessed claims you'd never put on a CV, internal hostnames, client names. A public repo linked from a CV or profile discloses whatever it contains to every reader, permanently and outside the context you'd have chosen. Extend the pattern whenever a new private signal surfaces; never narrow it.
3. Know the CLI/UI boundary. gh owns topics, description, file commits, pushes — do those. gh cannot set pin order or upload a social-preview image — those are UI-only, go on the todo list every time, and are never faked via API.
4. A README that lies is worse than one that's ugly. Surgical edits only. NEVER "fix" a path/command without verifying it's actually stale (read the tree, run it, check the file exists). A confidently wrong README is a credibility hit.
5. Surgical, read-before-edit, conservative. Touch only what improves presentation. No refactors, no reformatting untouched sections, no deleting what you didn't add. Match the repo's voice.

Workflow

1 — SURVEY (delegate when you can; get the conclusion, not the file dumps)

Surveying means reading the README end-to-end, the whole file tree, and the metadata — a lot of context that collapses to a short gap list. If your environment supports subagents, delegate it to one pinned to a cheaper model (e.g. pass model: sonnet) so that reading never lands in the main window — mechanical survey work shouldn't inherit an expensive session model. Brief it to return only the structured gap report below, no file contents, no narration. The exception is . (cwd), where the main session already holds the repo — survey inline then. If you can't delegate, survey inline but still distill to the report before acting.

Survey steps:

• Get the code: for <owner>/<repo>, shallow-clone to a temp dir (git clone --depth 1 https://github.com/<owner>/<repo>). For ., read cwd.
• Metadata: gh repo view <owner>/<repo> --json name,description,repositoryTopics,licenseInfo,homepageUrl,visibility. Confirm it's PUBLIC. If private, stop and report that — don't survey further.
• Read: README end-to-end, top-level file/dir layout, languages, any docs/ or workflows/. Understand the real shape of the project.

Return ONLY this report:

• visibility + default branch
• description: current value + verdict (weak/empty/fine)
• topics: current set + missing searchable ones from the real stack/domain
• license: present? (if absent on a portfolio repo, flag)
• README weaknesses: bulleted (wall/stub, no hook, no worked-example frame, stale paths, etc.)
• private-data risks spotted: any real names/paths/keys to scrub
• accurate paths/commands to PRESERVE verbatim

2 — PLAN (one printout, then go)

From the gap report, print ONE short, prioritized plan — what you'll change and why, grouped by the steps below, each marked [CLI] (you do it) or [UI] (the user's todo list). Lead with the highest-leverage gaps; keep it scannable, not an essay. This is the single approval surface: a normal run proceeds straight through; --dry-run stops here.

3 — EXECUTE (autonomous, atomic commits, push)

Do everything [CLI] in one pass. Commit each logical change atomically with a clear message; push when done. No per-step approval gates.

Idempotency — this skill gets re-run on the same repo. Each step below is conditional on a real gap from the survey, not a fixed to-do. A README already in the worked-example frame needs no rewrite; a description that's already sharp needs no edit. Re-do only what's genuinely stale or missing. A churn commit, or a rewrite of a fine README, violates rule 5 — on an already-polished repo the correct run is a no-op verify pass, reported as such.

a. Metadata.

• Topics: gh repo edit <owner>/<repo> --add-topic a,b,c — real, searchable, from the actual stack/domain.
• Description: gh repo edit <owner>/<repo> --description "<one sharp line>" — concrete, no fluff: what it is and what makes it interesting.

b. README polish. Surgical edits toward the worked-example frame:

• Strong title + one-line hook.
• "What this is" framing — for a portfolio repo the strongest honest frame is usually "the system I built for X; treat it as a worked example, not a template". It turns a personal project into a credibility signal.
• Clear sections (what's in here, how it works, quick start) sized to the repo; honest placeholder labels on any sample data; collapsible <details> for long blocks.
• Preserve every accurate path/command (rule 4).

c. LICENSE. If a public portfolio repo has none, flag it and offer MIT (a safe default). Add only on a clear yes — never silently.

d. Branded assets — OPTIONAL, only if the rendering add-on is installed. Check for it: test -d <skill-dir>/render && test -f <skill-dir>/render/brand.py. If absent, skip this step entirely — the core above is complete without it; do not tell the user assets were produced. If present, you may render an on-brand social card, README banner, and (only when there's real structure) an architecture diagram, all from one small per-repo config. Resolve the owner first (gh api user --jq .login) so the assets show the user's handle. Before picking an accent, check what's already taken across your other configs (grep -h '"accent"' configs/*.json) so sibling repos don't collide. Full schema, the accent palette, render commands, and where each file goes are in render/brand-spec.md — follow it. The integrity rules still bind: honest placeholder copy only, no faked diagrams, and the card is staged for the user to upload (the API can't — rule 3), never claimed as done.

Verify before done. If the README references any committed image under docs/ (e.g. one the user added themselves), curl each raw URL for a 200 before declaring done — a broken image is worse than none: curl -s -o /dev/null -w "%{http_code}" https://raw.githubusercontent.com/<owner>/<repo>/<default-branch>/docs/<file>. (Embeds using relative repo paths render natively on github.com and are outside this check.)

4 — HAND BACK: "YOUR TURN" (GitHub UI only)

Close with a clear, ordered todo list of what only the human + web UI can do — precise paths, exact UI locations:

• Pin order — which repos to pin and in what order, one-line reasoning each (lead with the strongest for the user's profile).
• Social-preview image — Settings → General → Social preview → Upload an image. gh can't do this (rule 3). If the rendering add-on is installed and you produced a card in step d, give the exact staged PNG path to upload. Otherwise any 1280×640 image works (and the add-on in SETUP.md can generate an on-brand one).
• Real-usage captures — if any asset needs a genuine screenshot, give a precise capture walkthrough (what to open, what state, what to frame, where to save). Never fabricate (rule 1).

Toolchain

• gh (authenticated) for all GitHub reads/writes. That's the only hard dependency of this core.
• git + curl (present on any dev machine).