Oss Polish

Open Source Project Polish

One-pass workflow to turn a bare repo into a professional, discoverable open source project. Four phases: README → topics/About → commit-history narrative → trending-repo positioning.

When to use

• Preparing a project for public release or first launch
• Repo has working code but a bare README, missing topics, or no About description
• Want a commit-history narrative (REPOSITORY_SUMMARY.md + THE_STORY_OF_THIS_REPO.md)
• Researching trending repos in a domain for positioning benchmarking
• Triggers on "polish my repo", "beautify open source project", "开源项目美化", "优化项目展示"

Not for: open source business model or commercialization strategy (use oss-strategy), or general project documentation (use documentation-audit).

Steps

Step 1: Analyze project

1. Read entry files (package.json, go.mod, Cargo.toml, requirements.txt, mkdocs.yml).
2. Scan source dirs for architecture and key features; note tech stack, target users, unique value.
3. Check existing README.md and repo metadata.
4. If README.md exists, ask: update in place or back up to README-backup.md first?

Result: a one-paragraph summary of what the project does, who it's for, and what's special.

Step 2: Generate README

Produce a professional README.md with sections in this order:

1. Title (H1) — repository name.
2. Badges — shields.io format. Order: build status → tech stack → hosting → license.

Pick templates from references/badges.md. Limit 5–10 for readability. Do NOT add a self-link "GitHub repo" badge — readers are already on GitHub.

1. Live site link — if deployed (GitHub Pages, Netlify, Vercel).
2. Overview — 1–3 paragraphs answering what / who / why / unique. Hook a visitor in `; emit a

| Metric | Count | table (markdown files, words, chapters, glossary…). For code-focused repos, skip this step — github_fetcher.py covers repo metrics instead.

1. Getting Started — prerequisites, clone, install, build/serve, deploy.
2. Repository Structure — concise ASCII tree (10–20 lines), representative not exhaustive.
3. Reporting Issues — link to GitHub Issues + bug-report template.
4. License — match LICENSE file / mkdocs.yml copyright; default CC BY 4.0 for

educational content (CC BY-SA if share-alike is desired); reserve NC (NonCommercial) only for projects that explicitly restrict commercial use, MIT or Apache-2.0 for code.

1. Acknowledgements — key dependencies only.
2. Contact — maintainer info.
3. Optional — Contributing, Citation (BibTeX), Changelog.

Formatting: ATX headers, blank line before lists, code fences with a language tag, lines env var to list repos by stars; inspect each repo's topics` field.

1. Identify 8–15 highly relevant topics; rank by discoverability × relevance × search volume.
2. Select the final list (max 20 — GitHub limit).
3. Write the About description (GitHub allows ≤350 chars): one compelling sentence

covering what + who + why.

Present the final list + rationale to the user before applying. Apply via GitHub API (PUT /repos/:owner/:repo/topics) and repo settings (description).

Step 4: Commit-history narrative story

Generate two files in the repo root using git data as evidence — write the files directly, do NOT paste markdown to chat.

• REPOSITORY_SUMMARY.md — overview, architecture, key components, technologies, data

flow, team/ownership.

• THE_STORY_OF_THIS_REPO.md — chronicles (year in numbers), cast of characters

(contributors + specialties), seasonal patterns, great themes (feat/fix/refactor), plot twists/turning points, current chapter.

Git commands to run systematically (POSIX forms for Git Bash):

• git rev-list --all --count — total commits
• git shortlog -sn --since="1 year ago" | head -20 — top contributors
• git log --since="1 year ago" --format="%ai" | cut -c1-7 | sort | uniq -c | sort -rn | head -12 — monthly activity
• git log --since="1 year ago" --oneline --grep="feat\|fix\|update\|add\|remove" | head -50 — change themes
• git log --since="1 year ago" --name-only --oneline — hotspot files
• git log --since="1 year ago" --merges --oneline | head -20 — collaboration patterns

Be specific: actual file names, commit messages, contributor names. Evidence-based — explain why patterns exist (holidays, releases, incidents).

Step 5: Trending-repo positioning

1. Run python references/scripts/github_fetcher.py with TOPIC= to fetch top

repos by stars.

1. Run python references/scripts/readme_fetcher.py (or the batch helper) to pull competitor

README summaries.

1. Benchmark: how does this project compare on stars, README quality, topic coverage, positioning?
2. Produce: a 5–10 word tagline, recommended launch channels (HN / Reddit / Dev.to /

DevHunt by domain), and a short positioning paragraph noting differentiators.

GH_TOKEN env var is optional but recommended (5000 req/hr authenticated vs 60 unauthenticated).

Step 6: Consolidated report

Output a single report:

# [Project Name] Open Source Polish
## Analysis Summary    — what / stack / audience
## README              — full content or diff
## Topics & About      — About (≤350 chars), topics list, rationale
## Narrative           — links to the two generated .md files
## Positioning         — tagline, launch plan, differentiators
## Next Steps          — apply checklist (README, topics, About, LICENSE)

After user approval, apply changes via your available GitHub tooling — the gh CLI or GitHub MCP (create_or_update_file for README/LICENSE; GitHub API PUT /repos/:owner/:repo/topics for topics; repo settings for the About description).

Output: README.md (polished) + REPOSITORY_SUMMARY.md + THE_STORY_OF_THIS_REPO.md (commit-history narrative), plus topics/About applied via GitHub API.

Verify

• [ ] README conforms to best practices — run

python references/scripts/validate-readme.py README.md; score ≥75/100 and no missing required sections (overview, getting started, license, contact).

• [ ] Topics set on the repo (1–20 topics, all relevant to the project's domain).
• [ ] About description set (≤350 chars, covers what + who + why).
• [ ] Both narrative files (REPOSITORY_SUMMARY.md, THE_STORY_OF_THIS_REPO.md) exist in repo

root with complete content (not chat output).

• [ ] Badge URLs resolve; no self-link GitHub-repo badge; all README links work.
• [ ] Positioning report includes tagline, launch channels, and ≥1 differentiator vs trending repos.

References

• [${CLAUDEPLUGINROOT}/references/engineering-principles.md](${CLAUDEPLUGINROOT}/references/engineering-principles.md) — discipline every skill shares.
• [references/badges.md](references/badges.md) — shields.io templates by category (languages, hosting, license, status, custom).
• [references/scripts/](references/scripts/) — collect-site-metrics.py (README metrics), validate-readme.py (README linter, scores 0–100), github_fetcher.py + readme_fetcher.py + config.py (trending-repo research via GitHub API).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: int2t05
• Source: int2t05/engineering-skills
• License: MIT

Install and usage instructions live in the source repository linked above.