oss_contributor_onboarding v1.0.0

name: "oss_contributor_onboarding" description: "Designs the path from stranger to first merged contribution on an open source project: a contributor path audit of the health files and contributing guide, a good first issue queue scored for whether each issue is truly starter sized, a cold clone to passing tests run timed on a clean machine, published review response targets, and recognition for first timers. Ships a runnable audit and scoring tool and a worked example. Triggers when a project gets few outside contributions, when someone asks how to attract or onboard open source contributors, set up good first issues, write or fix a CONTRIBUTING file, or why first pull requests stall or never get a second one." metadata: { "includeInPrompt": true }

OSS Contributor Onboarding

Purpose

Help a maintainer turn a repository that accepts contributions in theory into one a stranger can actually contribute to, and prove it with three checks instead of opinions. The path has five stages, and people drop out at each one: land on the project, get it running, pick a first task, survive review, and get recognized so they come back. The Open Source Guides call this the contributor funnel and put the job plainly: cut friction at each stage, because easy wins make people want to do more. Research on newcomers keeps finding the same drop points: no support materials, a steep setup curve, slow or absent feedback, and trouble finding a way to start.

This skill differs from a general DevRel or community skill in one way: it tests the path cold. Files existing is not the same as the setup working on a machine that has never seen the project, and a label on an issue is not the same as the issue being finishable by a newcomer. Every claim the project makes to strangers gets a run that can fail.

Workflow

1. Run the contributor path audit first. Run bin/contributor_audit.py audit <repo_path> against the local checkout. It checks for README, CONTRIBUTING, CODE_OF_CONDUCT, LICENSE, SECURITY, and SUPPORT files, issue templates, a pull request template, and CODEOWNERS, then checks whether CONTRIBUTING actually covers setup, tests, the pull request steps, behavior expectations, and how to claim an issue. Scores run 0 to 100. Treat a missing README, CONTRIBUTING, LICENSE, or CODE_OF_CONDUCT as a blocker whatever the total says. Fix blockers before anything else in this workflow.
2. Write or repair CONTRIBUTING so a stranger can act on it alone. GitHub surfaces this file when someone opens an issue or pull request, so write it for that moment. Put it in root, docs, or .github, knowing GitHub shows the .github copy first if several exist. It must contain, in order: prerequisites with versions, the exact setup commands, the exact test command and what passing output looks like, how to claim an issue or ask a question, the branch and pull request steps, what review to expect and how long it usually takes, and a link to the code of conduct. Adopt a code of conduct if none exists. Contributor Covenant 2.1 is the common default, with a four level enforcement ladder from Correction to Permanent Ban. A code of conduct with no named reporting contact is decoration.
3. Run the cold clone test, and let it fail honestly. On a clean machine or a fresh container, with no project tools preinstalled, one tester who did not write the setup docs clones the repository and follows only the written steps, timing two stages: clone to a running or built project, and from there to a passing test run. Record hard blockers and any step that worked only because the tester already knew it. Score it with bin/contributor_audit.py cold-clone --setup-minutes N --test-minutes N --blockers N --undocumented-steps N. The default budget is 30 minutes total. A project may set its own budget with --budget-minutes, and must write the budget down in CONTRIBUTING next to the setup steps. A fail means fix the docs or the setup, in the tester's words, then rerun from a fresh clone. The maintainer never runs this test on their own machine as the evidence. Their machine already has everything, so it cannot fail the way a stranger's does.
4. Build the good first issue queue by scoring, not by labelling on a hunch. Export candidate issues to the CSV shape in the tool header and run bin/contributor_audit.py score-issues <issues.csv>. Each issue scores on files touched, acceptance criteria present, reproduction steps or a worked example present, kind of task, and days since a maintainer last confirmed the scope. Two conditions block an issue outright, whatever its score: an unresolved design decision a newcomer cannot settle alone, and an issue already assigned or with a linked pull request. Research supports the shape: first tasks with few files, low prior knowledge needs, and clear descriptions get accepted more, and documentation and minor fix tasks lower the bar further. Keep at least three true starters live at once. Three is a planning floor from this skill, so the queue still offers a choice after one issue is claimed or goes stale. Re-score the queue monthly and strip the label from anything blocked, taken, or unconfirmed for over 90 days.
5. Write every starter issue to the same contract. Title that states the change plainly. Current behavior and expected behavior. Reproduction steps or an example of the input and the wanted output. Acceptance criteria a newcomer can check themselves. The files or area to look at first. What is out of scope. One named place to ask questions, and permission to ask them in the issue thread. If a maintainer cannot write the acceptance criteria, the issue is not scoped yet, and giving it a friendly label does not change that.
6. Publish review response targets and keep them. Set the targets in CONTRIBUTING as commitments the project chooses, for example: first human response to a first time issue or pull request within 2 business days, first review on a first pull request within 5 business days, and a merge or close decision with a reason on every first pull request. Those numbers are examples of a project commitment, not a standard anyone else verified. Measure time to first response the CHAOSS way: time of first response minus time the activity was created, counting maintainer responses and filtering bots out, and state that filter wherever the number is reported. A close with a clear reason and a pointer to a better fitting issue keeps a contributor. Silence loses them. The Guides put the outer limit bluntly: no response for a month and the person has likely forgotten the project.
7. Close the loop with recognition in the same week. Thank the contributor in the pull request thread by name, then record the contribution in a visible contributors list. Follow the All Contributors pattern: a Contributors section in the README, or a linked CONTRIBUTORS file when the list outgrows it, with each person's name, link, and contribution category, covering code and also documentation, review, translation, design, and answering questions. Recognize people as soon as the contribution is found, not in a batch months later, and invite contributors to add themselves. Recognition that only counts code teaches everyone else their work does not count.
8. Measure the path monthly with two numbers and act on the worse one. One: median time to first human response for first time issues and pull requests, bots filtered out. Two: of the people whose first pull request merged, how many opened a second one. The first number shows whether review keeps its promises. The second shows whether the path leads anywhere. If first timers merge once and never return, fix the queue depth and the review tone before spending anything on promotion. A project does not have an attraction problem until those two numbers say the path works.

Output Contract

A finished onboarding pass always contains:

• The audit output: score, verdict, and every missing health file or missing CONTRIBUTING topic named, with blockers listed separately
• The repaired CONTRIBUTING file, or a change list for it covering setup, tests, claiming, pull request steps, review expectations, and the code of conduct link
• The cold clone record: tester, machine or container used, setup minutes, test minutes, budget, blockers, undocumented steps found, and pass or fail, with the fix list if it failed
• The scored queue: every candidate issue with its score, verdict, blockers, and notes, plus the count of true starters and the label removals
• At least three starter issues rewritten to the issue contract in step 5, or a written reason the backlog cannot yield three yet and what will be scoped next
• The published response targets, with the measurement filter stated (maintainer responses, bots excluded)
• The recognition setup: where the contributors list lives, which contribution categories it covers, and who adds first timers and when
• The two monthly numbers from step 8, or the date the first measurement will run if the project has no first timers yet

Operating Rules

1. Accuracy rule: every factual claim about a platform, standard, or study must trace to a verified source (see references/research-brief.md). Never invent numbers, dates, or quotes. Response targets, budgets, queue floors, and audit scores in this skill are planning targets and decision rules, and must be presented that way, never as industry averages or findings.
2. Files are not proof. Never report a project as contributor ready on the audit alone. The cold clone run is the evidence for the setup, and it must run on a clean environment with a tester who did not write the docs.
3. A label is a promise. Never leave the good first issue label on an issue that is blocked on a design decision, already claimed, or stale. Stripping a bad label is a fix, not a loss.
4. Quality over cadence: if the backlog cannot produce three honest starters, say so and scope new ones. Never shrink the definition of starter sized to fill the queue.
5. Count humans in the response metric. Bot comments, CI notices, and auto labels are not a first response, and reporting them as one hides the exact failure this skill exists to catch.
6. Recognition covers non code work from the start. Adding categories later, after documentation and support contributors have already gone unlisted, does not repair the signal the first list sent.
7. The worked example in references/worked-example.md shows all three tool runs with their real output, from a 0 of 100 audit to a passing cold clone. Follow its order: audit, queue, cold run, then targets and recognition.