# Repo Upgrade

> Implement the 10 "repo to product" tips (Mateusz Pusz) in a repository — scaffold issue templates, dev containers, CONTRIBUTING/CONTRIBUTORS, README pitch, CI matrix with reproducible seeds, Diátaxis docs structure, release announcements, AI-contribution policy, and zero-install demos. Use when the user asks to improve, fix, upgrade, professionalize, or productize a repo's onboarding, docs, packaging, CI, or contributor experience; or says "repo upgrade", "apply the tips", "fix my README", "add issue templates", "add a devcontainer", "make my repo contributor-friendly". Accepts a tip number or name to apply just one. Pair with repo-audit to find what's missing first.

- Skill: `breed/repo-upgrade` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add breed/repo-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breed/repo-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: breed (https://skillmd.com/u/breed)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/breed/repo-upgrade

---


# Repo Upgrade

Apply the ten "repo to product" tips to a repository. Companion to `repo-audit`, which identifies what's missing.

**Guiding constraint from the talk:** *don't implement all ten at once — start with one this week and try the next a month from now. Repo to product is a journey, not a sprint.* Default to a focused change, not a 10-item sweep.

## Workflow

1. **Scope it.** If the user named a tip (`/repo-upgrade 6`, `/repo-upgrade devcontainer`, "add issue templates"), do that one. If they said "apply the tips" broadly, run `repo-audit` first — or read an existing `REPO-AUDIT.md` — and propose the top three. Do not start writing files across all ten.
2. **Detect the ecosystem** before writing anything. Read `../repo-audit/references/ecosystems.md` if reachable; otherwise infer from marker files. Every asset in `assets/` is a starting point that must be adapted — a Python repo gets a Python CI matrix, not the C++ one.
3. **Read before writing.** Never overwrite `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, or any CI workflow without reading it first and preserving what's there. These files usually contain project-specific content worth keeping.
4. **Implement** using `references/playbooks.md` — per-tip steps, decisions, and pitfalls.
5. **Verify.** Lint YAML you generate. If you touched CI, at minimum check the workflow parses. If you touched packaging, run the install-verification test you added.
6. **Summarize** what changed, what the user must fill in (placeholders), and what to do next month.

## Safety rules

- **Scaffolding new files: go ahead.** Issue templates, `devcontainer.json`, `CONTRIBUTORS.md`, docs skeletons, PR templates — these are additive and safe.
- **Editing existing CI, build, or packaging files: show the diff and get agreement first.** A broken `CMakeLists.txt`, `pyproject.toml`, or workflow costs the user real time. Propose, don't surprise.
- **Never invent facts about the project.** Don't write a value proposition claiming performance or standards compliance you haven't verified. Leave a clearly marked `<!-- TODO -->` and ask.
- **Never fabricate contributor names, testimonials, adoption claims, or badge states.** Populate `CONTRIBUTORS.md` from `git log`, not from imagination. A badge must point at a workflow that actually exists.
- **Don't commit or push** unless asked. If the repo has no git history yet, say so rather than running `git init` uninvited.
- **Respect existing conventions.** If the repo uses `.rst`, don't switch it to Markdown. If it uses GitLab CI, don't scaffold GitHub Actions.

## Assets

`assets/` holds templates to copy and adapt:

| Path | For |
|---|---|
| `github/ISSUE_TEMPLATE/bug_report.yml` | Tip 3 — repro-link-first bug reports |
| `github/ISSUE_TEMPLATE/feature_request.yml` | Tip 3 |
| `github/ISSUE_TEMPLATE/docs_issue.yml` | Tip 3 |
| `github/ISSUE_TEMPLATE/production_experience.yml` | Tip 10 — surface the silent happy users |
| `github/ISSUE_TEMPLATE/config.yml` | Tip 3 — route questions to Discussions |
| `github/pull_request_template.md` | Tip 9 — the "why" field |
| `github/workflows/matrix-fuzz.yml` | Tip 2 — randomized matrix with reproducible seed |
| `devcontainer.json` | Tip 6 |
| `CONTRIBUTING.md` | Tips 6 + 9, includes the AI policy |
| `CONTRIBUTORS.md` | Tip 9 |
| `RELEASE_TEMPLATE.md` | Tip 8 |
| `README_SKELETON.md` | Tip 1 |

Placeholders are written as `{{LIKE_THIS}}` — every one must be resolved or explicitly raised with the user. Do not ship a file containing an unresolved placeholder without saying so.

## Reference

Source notes: `TIPS.md` in the repo-to-product repo (talk: https://www.youtube.com/watch?v=DWXlyOd_z88).