# Oss Repo Readiness > Audit and prepare a GitHub repo for open source release, with a focus on developer experience (DevEx) — the things that determine whether a stranger can go from "found this repo" to "opened a PR" without friction. Use this whenever the user wants to open-source a repo, make a private repo public, do a "pre-launch checklist" or "OSS readiness audit," improve their README/CONTRIBUTING/issue templates, or asks something like "is this repo ready for people to use/contribute to." Also trigger for narrower asks that are really pieces of this — "write a CONTRIBUTING.md," "set up issue templates," "add a CODEOWNERS file" — since those are almost always better done as part of the full readiness pass rather than in isolation. - Skill: `markphelps/oss-repo-readiness` (Agent Skill) - Install (CLI): `npx skillmds@latest add markphelps/oss-repo-readiness` - Raw SKILL.md: https://api.skillmd.com/api/skills/markphelps/oss-repo-readiness/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: markphelps (https://skillmd.com/u/markphelps) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/markphelps/oss-repo-readiness --- # Open Source Repo Readiness Getting a repo "open source ready" isn't about the license — that's a five-minute checkbox. It's about DevEx: whether a developer who has never talked to the maintainer can understand the project, run it, and land a contribution without having to ask a question first. Every piece of friction you remove here is a contributor you don't lose. This skill audits a repo against that bar, using patterns pulled from repos that are genuinely good at this (Vite, shadcn/ui, tRPC, Sentry, Supabase, Rust, Excalidraw, Caddy) rather than generic checklist advice. ## Workflow 1. **Inspect the repo.** Read the root directory listing, README, package manifest (package.json / Cargo.toml / go.mod / pyproject.toml), CI config, and any existing docs. Figure out the language/ecosystem and how big the project is — a 200-star CLI and a framework with a plugin ecosystem need different amounts of ceremony. Don't assume; look. 2. **Run the audit** using the checklist below. Produce a short gap report: what exists, what's missing, what exists but is weak (e.g. a README with no quickstart, a CONTRIBUTING.md that's just a boilerplate stub). 3. **Propose, don't dump.** Share the gap report and ask which pieces to tackle — or if the user says "just do it," proceed through the checklist in priority order (Tier 1 first). Don't generate all nine files unprompted for a repo that only asked about its README. 4. **Write files that reflect the actual repo**, not placeholders. Pull the real install command from the manifest, the real test command from CI config or package scripts, the real license the user wants, the real project name. A generated CONTRIBUTING.md that says `npm test` in a Go repo is worse than no CONTRIBUTING.md. 5. **Flag what you can't decide for them**: license choice (MIT vs Apache-2.0 vs GPL has real implications — explain the tradeoff, don't just pick one), whether to enable Discussions, whether to add a CLA. Ask rather than assume for anything with legal or governance weight. ## The audit, in priority order ### Tier 1 — the first five minutes of a stranger's visit These are what someone sees before they've run a single command. Weak here, and nothing else matters. - **README.md** — this is the actual product page, not a formality. It needs, in order: a one-line description that says what problem this solves (not what it's built with), a quickstart that gets someone running something in under 60 seconds, and only then everything else. The Vite and shadcn/ui READMEs both lead with "what is this" before any badge or table of contents. If there's a UI, a screenshot or short GIF above the fold does more than three paragraphs of description — this is the single highest-leverage thing you can add to a README with a visual component. Cut anything that belongs in `/docs` instead: full API reference, architecture deep-dives, and changelog entries don't belong in the README — link to them. - **LICENSE** — no license file means the code is not legally usable by anyone, full stop, regardless of what the README says. If the user hasn't chosen one, ask: MIT/Apache-2.0/BSD for "I want maximum adoption, don't care much what people do with it" (most dev-tool repos, including basically all of the ones referenced in this skill); Apache-2.0 specifically if patent grant language matters (common for anything that touches larger companies' legal review, e.g. Kubernetes-ecosystem projects); GPL/AGPL for "I want derivative works to stay open" (used deliberately by projects like Grafana pre-relicense, or database/infra tools wary of cloud providers repackaging them). - **Quickstart that actually works** — the single most common OSS-readiness failure is a copy-pasted install command that's stale. Before treating the README as done, mentally (or actually) walk it as a first-time user would: clone, install, run — does the first command in the doc actually work against the current repo state? ### Tier 2 — the first contribution Everything a person needs to go from "I found a bug" or "I want to add X" to a merged PR without a synchronous conversation. - **CONTRIBUTING.md** — dev environment setup, how to run tests, branch/commit conventions if any, and what the PR review process looks like (response-time expectations help — tRPC and Sentry both state roughly how fast maintainers respond). If the project uses a specific commit format (Conventional Commits is the common one, used by Vite/Vue/Angular-descended projects because it drives automated changelogs/semver), say so explicitly with an example, not just a link to the spec. - **Issue templates** (`.github/ISSUE_TEMPLATE/`) — GitHub's issue _forms_ (YAML, not just markdown templates) are the current standard: structured fields for repro steps, environment, expected vs actual behavior. Bug report + feature request at minimum. A blank issue box gets you "it doesn't work" with no repro; a form gets you something actionable. Include a `config.yml` that points support questions to Discussions instead of Issues if Discussions is enabled — keeps the issue tracker from filling with questions. - **Pull request template** (`.github/pull_request_template.md`) — a short checklist (tests added, docs updated, linked issue) catches the common gaps before review rather than after. - **"Good first issue" labeling** — not a file, but worth flagging: GitHub's own research found repos where ~25% of open issues are labeled "good first issue" see meaningfully more first-time contributors than those without. If the repo has open issues and none are labeled, that's a cheap, high-leverage fix — ask the user if they want help identifying 3-5 candidates from the current issue list. - **CODEOWNERS** (`.github/CODEOWNERS`) — only worth adding once there's more than one maintainer or the repo has distinct areas of ownership; skip for solo-maintainer projects, it's pure overhead there. ### Tier 3 — trust and governance signals These matter more as the project grows past "a few people trying it" — don't over-invest here for a brand-new repo, but flag them as the project matures. - **CODE_OF_CONDUCT.md** — the Contributor Covenant is the de facto default; almost no project needs a custom one. Its main value isn't the document itself, it's signaling "this is a maintained, professional space" to a first-time contributor deciding whether to engage. - **SECURITY.md** — even a few lines (how to report a vulnerability privately, e.g. a security@ email or GitHub's private vulnerability reporting) matters the moment the project has real users, because the alternative is someone disclosing a vulnerability in a public issue. - **CHANGELOG.md** — Keep a Changelog format (or auto-generated from Conventional Commits via changesets/semantic-release) tells people what changed between versions without reading commit history. Auto-generated is far more sustainable than hand-maintained for anything with regular releases. - **Governance / MAINTAINERS file** — only for projects with multiple maintainers or that want to signal a path from contributor to maintainer. Skip for solo projects. - **FUNDING.yml** (`.github/FUNDING.yml`) — only if the maintainer actually wants funding/sponsorship; trivial to add (GitHub Sponsors, Open Collective, etc.) and shows up as a "Sponsor" button on the repo. ### Tier 4 — DevEx polish The difference between "usable" and "a pleasure to contribute to." Higher effort, worth it for projects expecting sustained outside contribution. - **CI on every PR** — tests + lint + build running automatically and visibly (a status check on the PR, plus a badge in the README) is table stakes for trust; a contributor shouldn't have to wonder if their change broke something. - **Devcontainer / one-command setup** (`.devcontainer/`, or a `Makefile`/`justfile`/npm script that does everything) — removes "what version of X do I need" as a source of friction entirely. Rust projects lean on `cargo` doing this for free; polyglot or C-dependency-heavy projects benefit the most from an explicit devcontainer. - **Discussions enabled** — for Q&A and proposals that shouldn't live in the issue tracker. Worth enabling once the issue tracker starts accumulating "how do I..." questions. - **Badges that mean something** — build status, license, latest version, and maybe a Discord/Slack invite if community chat exists. Skip decorative badge walls; each one should answer a real question a visitor has ("does this still work," "what license," "can I ask a question somewhere"). A star-history chart is a nice-to-have late addition, not a priority. - **Repo topics + a real "About" description** — cheap, easy to forget, and is how people find the repo via GitHub search/topic browsing at all. ## Writing the actual content When generating README/CONTRIBUTING/templates, don't reach for boilerplate. Base every command on what's actually in the repo: - Pull the run/build/test/lint commands from `package.json` scripts, `Makefile` targets, `Cargo.toml`, CI workflow files, or existing docs — don't guess at conventional command names. - Match the project's actual tone. A terse, code-forward CLI dev-tool README (think ripgrep or fd) reads differently from a README for a broader application-facing OSS project (think Excalidraw or Supabase). - If the repo has no tests yet, don't write a CONTRIBUTING.md section instructing contributors to run tests that don't exist — flag the gap instead and ask if they want a minimal test setup first. - Keep the README's first screen (before any scroll) to: name, one-line pitch, and the quickstart. Everything else — full docs, architecture, FAQ — can live below the fold or in `/docs`, linked rather than inlined. ## Output Default to writing the files directly into the repo at their conventional paths (`README.md`, `CONTRIBUTING.md`, `.github/ISSUE_TEMPLATE/*.yml`, etc.) rather than dumping content into chat — these are meant to be committed. Summarize what was added/changed and call out anything that still needs a human decision (license choice, whether to enable Discussions, who owns CODEOWNERS entries) rather than silently picking for them.