github-repo-hygiene-skill

The problem

A repo with no description, no topics, no license, and a README that still says "This project was bootstrapped with create-next-app" reads as abandoned, even when the code behind it is solid. Nobody does this on purpose, it's just the stuff that's easy to forget once the thing works. Anyone vetting a developer, a recruiter, a client, another dev checking your work, starts on GitHub, and a sparse profile costs you before they've read a line of code.

What it audits and fixes

It checks every repo (or a specific one) for five things: missing description, missing topics, no license, no README, and a README that's still unedited scaffold text (create-next-app, create-react-app, and similar). The audit is read-only and reports findings before touching anything, grouped as clean repos, small gaps, and real problems. Nothing gets written without you seeing it and approving it first, a wrong or invented project description is worse than no description at all since it's your public profile. For anything it does fix, it reads the actual code first (package.json, existing docs, source files) rather than guessing, then writes descriptions and topics with gh repo edit, and rewrites thin READMEs through a real clone, commit, and push.

I ran it across my own account

Dogfooding is the honest test, so I ran it across my own GitHub, all 16 public repos. The first pass flagged 10 issues across 6 repos, but 2 of those were the audit marking my profile README repo (marcosmodly/marcosmodly) for having no topics and no license, which is exactly how a profile repo is meant to look. That's a bug in the tool, not my profile, so I added a rule that recognises the profile repo and skips those two checks for it, then re-ran. The real result: 11 clean, 5 with a genuine gap, 8 issues, all metadata: 4 repos with no license, 2 missing topics, 2 with no description. Nothing was missing a README or still carrying scaffold text, so two of the five checks found zero. Of the 8, the skill can set 2 itself, the missing topics, inferred from each repo's own code, and holds 6 back for me to approve, the descriptions and the license choices, because a tool guessing either of those on your public profile is worse than the gap it's filling. The full sweep, two GitHub API calls per repo, runs in about 40 seconds.

The scan is read-only and prints one JSON object per repo. The five that came back with something to fix:

$ ./audit_repos.sh marcosmodly

{"repo": "marcosmodly/grandmas-lighthouse", "is_fork": false, "is_profile_repo": false, "description": null, "topic_count": 0, "license": null, "readme_status": "present", "readme_looks_like_boilerplate": false, "issues": ["no description set", "no topics set", "no license"], "clean": false}
{"repo": "marcosmodly/portfolio", "is_fork": false, "is_profile_repo": false, "description": null, "topic_count": 0, "license": "MIT", "readme_status": "present", "readme_looks_like_boilerplate": false, "issues": ["no description set", "no topics set"], "clean": false}
{"repo": "marcosmodly/holdfast", "is_fork": false, "is_profile_repo": false, "description": "Voice-first memory for the people you care about...", "topic_count": 6, "license": null, "readme_status": "present", "readme_looks_like_boilerplate": false, "issues": ["no license"], "clean": false}
{"repo": "marcosmodly/modlyai", "is_fork": false, "is_profile_repo": false, "description": "AI-powered furniture recommendation and customization platform...", "topic_count": 7, "license": null, "readme_status": "present", "readme_looks_like_boilerplate": false, "issues": ["no license"], "clean": false}
{"repo": "marcosmodly/second-brain-ai", "is_fork": false, "is_profile_repo": false, "description": "A personal knowledge base for developers...", "topic_count": 10, "license": null, "readme_status": "present", "readme_looks_like_boilerplate": false, "issues": ["no license"], "clean": false}

# ...11 more lines, all "clean": true, including marcosmodly/marcosmodly
#    ("is_profile_repo": true -> topics and license checks skipped)
16 repos audited: 11 clean, 5 with a gap, 8 issues
   4 x no license   2 x no description set   2 x no topics set

Real output. Descriptions truncated here for width; the script prints them in full.

Ships as a reusable Claude Code skill

It's not a one-off script, it's a Claude Code skill: a SKILL.md with the audit/report/fix workflow plus a bash script (audit_repos.sh) that does the actual read-only scan against the GitHub API. Drop it into a Claude Code skills directory and it activates on its own whenever someone asks to clean up their GitHub, audit a repo, or mentions their profile looking sparse or unfinished, no need to name it directly.

Published as its own repo

github-repo-hygiene-skill, MIT licensed, real README, topics set, the works, which is a little bit the joke: the tool that fixes exactly this problem doesn't have this problem itself.