Skill v1.0.0
currentAutomated scan100/100version: "1.0.0" name: github-contributor description: Strategic guide for becoming an effective GitHub contributor. Covers opportunity discovery, project selection, high-quality PR creation, and reputation building. Use when looking to contribute to open-source projects, building GitHub presence, or learning contribution best practices.
GitHub Contributor
Strategic guide for becoming an effective GitHub contributor and building your open-source reputation.
Prerequisites
- Install GitHub CLI and verify availability:
gh --version - Authenticate before running commands:
gh auth status || gh auth login
The Strategy
Core insight: Many open-source projects have room for improvement. By contributing high-quality PRs, you:
- Build contributor reputation
- Learn from top codebases
- Expand professional network
- Create public proof of skills
Contribution Types
1. Documentation Improvements
Lowest barrier, high impact.
- Fix typos, grammar, unclear explanations
- Add missing examples
- Improve README structure
- Translate documentation
Opportunity signals:- "docs", "documentation" labels- Issues asking "how do I..."- Outdated screenshots or examples
2. Code Quality Enhancements
Medium effort, demonstrates technical skill.
- Fix linter warnings
- Add type annotations
- Improve error messages
- Refactor for readability
Opportunity signals:- "good first issue" label- "tech debt" or "refactor" labels- Code without tests
3. Bug Fixes
High impact, builds trust.
- Reproduce and fix reported bugs
- Add regression tests
- Document root cause
Opportunity signals:- "bug" label with reproduction steps- Issues with many thumbs up- Stale bugs (maintainers busy)
4. Feature Additions
Highest effort, highest visibility.
- Implement requested features
- Add integrations
- Performance improvements
Opportunity signals:- "help wanted" label- Features with clear specs- Issues linked to roadmap
Project Selection
Good First Projects
| Criteria | Why | |
|---|---|---|
| Active maintainers | PRs get reviewed | |
| Clear contribution guide | Know expectations | |
| "good first issue" labels | Curated entry points | |
| Recent merged PRs | Project is alive | |
| Friendly community | Supportive feedback |
Red Flags
- No activity in 6+ months
- Many open PRs without review
- Hostile issue discussions
- No contribution guidelines
Finding Projects
# GitHub search for good first issuesgh search issues "good first issue" --language=python --sort=created --state=open# Search by topicgh search repos "topic:cli" --sort=stars --limit=20# Find repos you use# Check dependencies in your projects
PR Excellence
The High-Quality PR Formula
Based on real-world successful contributions to major open-source projects:
1. Deep investigation (post to issue, not PR)2. Minimal, surgical fix (only change what's necessary)3. Regression test (prevent future breakage)4. CHANGELOG entry (if project uses it)5. End-to-end validation (prove bug exists, prove fix works)6. Clear PR structure (~50 lines, focused)7. Professional communication8. Separate concerns (detailed analysis in issue, fix summary in PR)9. No internal/irrelevant details10. Responsive to feedback
Before Writing Code
Pre-PR Checklist:- [ ] Read CONTRIBUTING.md- [ ] Check existing PRs for similar changes- [ ] Comment on issue to claim it- [ ] Understand project conventions- [ ] Set up development environment- [ ] Trace through git history for context- [ ] Identify root cause with evidence
Investigation Phase (Post to Issue)
Do this BEFORE coding:
- Reproduce the bug with exact commands and output
- Trace git history to understand context
``bash git log --all --grep="keyword" --oneline git blame file.ts | grep "relevant_line" ``
- Link related issues/PRs that provide context
- Post detailed analysis to issue (not PR)
- Timeline of related changes
- Root cause explanation
- Why previous approaches didn't work
Example structure:
## InvestigationI traced this through the codebase history:1.[Date]: #[PR] introduced [feature]2.[Date]: #[PR] added [workaround] because [reason]3.[Date]: #[PR] changed [parameter]4.Now: Safe to [fix] because [explanation][Detailed evidence with code references]
Writing the PR
Title: Clear, conventional format
feat(config): add support for YAML config filesfix(pool): resolve race condition in connection pooldocs(readme): update installation instructions for Windowsrefactor(validation): extract validation logic into separate module
Keep PR description focused (~50 lines):
- Summary (1-2 sentences)
- Root cause (technical, with code refs)
- Changes (bullet list)
- Why it's safe
- Testing approach
- Related issues
Move detailed investigation to issue comments, not PR.
Evidence Loop
Critical: Prove the change with a reproducible fail → fix → pass loop.
- Reproduce failure with original version
``bash # Test with original version npm install -g package@original-version [command that triggers bug] # Capture: error messages, exit codes, timestamps ``
- Apply fix and test with patched version
``bash # Test with fixed version npm install -g package@fixed-version [same command] # Capture: success output, normal exit codes ``
- Document both with timestamps, PIDs, exit codes, logs
- Redact sensitive info:
- Local absolute paths (
/Users/...,/home/...) - Secrets/tokens/API keys
- Internal URLs/hostnames
- Recheck every pasted block before submitting
Description: Focused and reviewable (~50 lines)
## Summary[1-2 sentences: what this fixes and why]## Root Cause[Technical explanation with code references]## Changes- [Actual code changes]- [Tests added]- [Docs updated]## Why This Is Safe[Explain why it won't break anything]## Testing### Test 1: Reproduce Bug (Original Version)Command: `[command]`Result:
[failure output with timestamps, exit codes]
### Test 2: Validate Fix (Patched Version)Command: `[same command]`Result:
[success output with timestamps, exit codes]
## Related- Fixes #[issue]- Related: #[other issues/PRs]
What NOT to include in PR:
- ❌ Detailed timeline analysis (put in issue)
- ❌ Historical context (put in issue)
- ❌ Internal tooling mentions
- ❌ Speculation or uncertainty
- ❌ Walls of text (>100 lines)
Code Changes Best Practices
Minimal, surgical fixes:
- ✅ Only change what's necessary to fix the bug
- ✅ Add regression test to prevent future breakage
- ✅ Update CHANGELOG if project uses it
- ❌ Don't refactor surrounding code
- ❌ Don't add "improvements" beyond the fix
- ❌ Don't change unrelated files
Example (OpenClaw PR #39763):
Files changed: 2- src/infra/process-respawn.ts (3 lines removed, 1 added)- src/infra/process-respawn.test.ts (regression test added)Result: 278K star project, clean approval
Separation of Concerns
Issue comments: Detailed investigation
- Timeline analysis
- Historical context
- Related PRs/issues
- Root cause deep dive
PR description: Focused on the fix
- Summary (1-2 sentences)
- Root cause (technical)
- Changes (bullet list)
- Testing validation
- ~50 lines total
Separate test comment: End-to-end validation
- Test with original version (prove bug)
- Test with fixed version (prove fix)
- Full logs with timestamps
After Submitting
- Monitor CI results
- Respond to feedback promptly (within 24 hours)
- Make requested changes quickly
- Be grateful for reviews
- Don't argue, discuss professionally
- If you need to update PR:
- Add new commits (don't force push during review)
- Explain what changed in comment
- Re-request review when ready
Professional responses:
✅ "Good point! I've updated the implementation to..."✅ "Thanks for catching that. Fixed in commit abc123."✅ "I see what you mean. I chose this approach because...Would you prefer if I changed it to...?"❌ "That's just your opinion."❌ "It works on my machine."❌ "This is how I always do it."
Building Reputation
The Contribution Ladder
Level 1: Documentation fixes↓ (build familiarity)Level 2: Small bug fixes↓ (understand codebase)Level 3: Feature contributions↓ (trusted contributor)Level 4: Maintainer status
Consistency Over Volume
❌ 10 PRs in one week, then nothing✅ 1-2 PRs per week, sustained
Engage Beyond PRs
- Answer questions in issues
- Help triage bug reports
- Review others' PRs (if welcome)
- Join project Discord/Slack
Common Mistakes
Don't
- Submit drive-by PRs without investigation
- Include detailed timeline in PR (put in issue)
- Mention internal tooling or infrastructure
- Argue with maintainers
- Ignore code style guidelines
- Make massive changes without discussion
- Ghost after submitting
- Refactor code unrelated to the fix
- Add "improvements" beyond what was requested
- Force push during review (unless asked)
Do
- Investigate thoroughly BEFORE coding
- Post detailed analysis to issue, not PR
- Keep PR focused and minimal (~50 lines)
- Start with small, focused PRs
- Follow project conventions exactly
- Add regression tests
- Update CHANGELOG if project uses it
- Communicate proactively
- Accept feedback gracefully
- Build relationships over time
- Test with both original and fixed versions
- Redact sensitive info from logs
Workflow Template
High-Quality Contribution Workflow:Investigation Phase:- [ ] Find project with "good first issue"- [ ] Read contribution guidelines- [ ] Comment on issue to claim- [ ] Reproduce bug with original version- [ ] Trace git history for context- [ ] Identify root cause with evidence- [ ] Post detailed analysis to issueImplementation Phase:- [ ] Fork and set up locally- [ ] Make minimal, focused changes- [ ] Add regression test- [ ] Update CHANGELOG (if applicable)- [ ] Follow project conventions exactlyValidation Phase:- [ ] Test with original version (prove bug exists)- [ ] Test with fixed version (prove fix works)- [ ] Document both with timestamps/logs- [ ] Redact paths/secrets/internal hostsSubmission Phase:- [ ] Write focused PR description (~50 lines)- [ ] Link to detailed issue analysis- [ ] Post end-to-end test results- [ ] Ensure CI passesReview Phase:- [ ] Respond to feedback within 24 hours- [ ] Make requested changes quickly- [ ] Don't force push during review- [ ] Thank reviewers- [ ] Celebrate when merged! 🎉
Quick Reference
GitHub CLI Commands
# Fork a repogh repo fork owner/repo --clone# Create PRgh pr create --title "feat(scope): ..." --body "..."# Check PR statusgh pr status# View project issuesgh issue list --repo owner/repo --label "good first issue" --state=open
Commit Message Format
<type>(<scope>): <description>[optional body][optional footer]
Types: feat, fix, docs, style, refactor, test, chore
References
references/pr_checklist.md- Complete PR quality checklistreferences/project_evaluation.md- How to evaluate projectsreferences/communication_templates.md- Issue/PR templatesreferences/high_quality_pr_case_study.md- Real-world successful PR walkthrough (OpenClaw #39763)
Success Indicators
You know you have a high-quality PR when:
- ✅ Maintainers understand the problem immediately
- ✅ Reviewers can verify the fix easily
- ✅ CI passes on first try
- ✅ No "can you explain..." questions
- ✅ Minimal back-and-forth
- ✅ Quick approval
Key Metrics for Quality PRs
Based on successful contributions to major projects:
- Files changed: 1-3 (focused scope)
- Lines changed: 10-50 (minimal fix)
- PR description: ~50 lines (concise)
- Issue investigation: 100-300 lines (thorough)
- Time to first draft: 2-3 days (proper investigation)
- Time to ready: 3-5 days (including validation)
- Response time: <24 hours (professional)