| name | open-source-playbook |
| description | Entry point and router for open-source work. Use when the user states an open-source goal without naming a specific task — "I want to open source this", "how do I grow this project", "make this repo look professional", "get more contributors", "prepare for v1.0" — or when a request touches several OSS concerns at once. Diagnoses which stage the project is in, then routes to the specific skill(s) that apply and sequences them. Do not use when the user already named a concrete task (writing a README, cutting a release, triaging issues) — go straight to that skill. |
Open Source Playbook
The router. Your job here is diagnosis before action: figure out what stage the
project is actually in, name the one or two bottlenecks that matter, and hand off to
the specific skills. Do not attempt to do all of open source in one pass.
Step 1 — Read the repo before advising
Never advise from the prompt alone. Spend two minutes on ground truth:
ls -la
git log --oneline -20
git shortlog -sn | head -20
gh repo view --json stargazerCount,forkCount,openIssues,createdAt,licenseInfo 2>/dev/null
gh issue list --limit 20 --state open 2>/dev/null
gh pr list --limit 20 --state open 2>/dev/null
Then read README.md, CONTRIBUTING.md, .github/workflows/, and the package
manifest. If gh is unavailable or unauthenticated, work from the local clone and say
so — do not fabricate repo statistics.
Step 2 — Locate the stage
| Stage | Signal | Bottleneck is almost always |
|---|
| 0. Pre-release | No public repo, or code exists but no license/README | Positioning and legal basics |
| 1. Published, unknown | Public, <50 stars, single contributor | The README and a working install path |
| 2. Discovered | Traffic arriving, issues opening, nobody contributing code | Contributor onboarding and docs |
| 3. Growing | Multiple contributors, PR queue forming | Automation, review throughput, triage |
| 4. Depended-upon | Downstream users, breakage complaints | API stability, release discipline, security |
| 5. Institutional | Many maintainers, org-scale | Governance, sustainability, succession |
Most projects are one stage behind where their owner thinks they are. Calibrate on
evidence (issue volume, external PRs, download counts), not ambition.
Step 3 — Route
| The user's goal | Skill to load |
|---|
| Start a repo from nothing | repo-bootstrap |
| Pick a license, handle CLA/DCO, vendored code | license-and-legal |
| Nobody understands what this does | readme-that-converts |
| Docs sprawl, users ask answered questions | docs-architecture |
| Public interface design, stability guarantees | api-design |
| Test suite is slow, flaky, or missing | testing-strategy |
| Review an incoming PR | code-review |
| Big rewrite without breaking users | refactor-safely |
| Performance claims, benchmark suite | performance-benchmarking |
| CI is slow, flaky, or absent | ci-pipelines |
| Versioning, changelog, publishing | release-engineering |
| SECURITY.md, provenance, scorecard, CVEs | supply-chain-security |
| Dependency bloat, upgrade churn | dependency-hygiene |
| Issue backlog is unmanageable | issue-triage |
| No one contributes; first PRs stall | contributor-experience |
| Launch, announce, grow adoption | launch-and-growth |
| Decision-making, burnout, funding, succession | governance-and-sustainability |
Load skills on demand, not preemptively. Two skills per response is usually the
ceiling before advice turns to mush.
Step 4 — Sequence, don't dump
Give the user an ordered plan with the smallest viable first step. A useful default
ordering by stage:
- Stage 0→1: license → README → install path that actually works → first release
- Stage 1→2: docs beyond the README → issue templates →
good first issue labels
- Stage 2→3: CI → contributing guide → triage rotation → release automation
- Stage 3→4: semver policy → deprecation policy → security policy → provenance
- Stage 4→5: written governance → funding → maintainer onboarding → succession
The compounding rule
Work that pays off repeatedly beats work that pays off once. Ranked by leverage:
- Automation — CI, releases, linting. Paid once, collected forever.
- Documentation — answers a question once instead of per-user.
- Contributor enablement — turns visitors into a second pair of hands.
- Marketing — real, but decays; it needs 1–3 in place to convert.
A project that grows on marketing alone with none of 1–3 collapses under its own
issue queue. Say this out loud when a user wants to skip to launch.
Honest framing
Skills encode the practices that well-run projects share. They do not manufacture
demand. If a project solves a problem nobody has, the correct advice is to change the
problem, not the README. Say that plainly when it is true — it is the single most
valuable thing a reviewer can tell a maintainer, and the hardest to hear.
Anti-patterns
- Advising without reading the repo. Generic advice is worthless and obvious.
- Boiling the ocean. An 18-point improvement plan gets zero points done.
- Vanity metrics as the goal. Stars follow usefulness; targeting stars directly
produces launch spikes and dead repos. Optimize for the second visit, not the first.
- Process before people. A governance document for a one-person project is
cosplay. Add process when the pain is real.
