Open Source Contributions
The Golden Rule
Make it easy for maintainers to absorb your contribution. Maintainers are often under-resourced volunteers or small teams. Every friction point you remove — unclear reproduction steps, missing tests, bad commit messages, force-pushed history — is time they don't have to spend figuring out what you did and why. The whole point is to help them, not create more work.
When to Use This Skill
- Filing a bug report or feature request on a public repository
- Preparing a pull request for any open source project
- Working on a project without documented contributing guidelines (default posture)
- Reviewing your own PR before submission
- Setting up open source conventions for your own project
Load the relevant phase reference for detailed instructions.
Quick Phase Overview
| Phase |
What It Covers |
Reference |
| 0a — Maintainer Conventions |
README discipline, LICENSE, CONTRIBUTING.md, issue/PR templates, commit conventions, DCO, release workflow hygiene |
references/phase-0a-maintainer-conventions.md |
| 0 — Before You Start |
Reading CONTRIBUTING.md, checking existing issues/PRs, triaging bugfix candidates, large-change discussion etiquette |
references/phase-0-before-you-start.md |
| 1 — Filing Issues |
Bug report and feature request templates, agent disclosure, maintainer workflow ("issue first"), coordinated multi-issue roadmaps, multi-PR plan execution |
references/phase-1-filing-issues.md |
| 2 — Pull Requests |
Branching conventions, scope assessment, studying existing implementations, cross-repo comparison, commit messages, PR templates, documentation audits, CI setup |
references/phase-2-pull-requests.md |
| 3 — After Submitting |
CI monitoring, responding to review feedback, what to do if your PR goes stale or gets closed |
references/phase-3-after-submitting.md |
| 3.5 — Follow-up After Scope Feedback |
Systematic call-site audits, filing comprehensive issues, complementary PRs when maintainer scope notes identify gaps |
references/phase-35-followup.md |
| 4 — Release Process |
Version bumping, tagging, GitHub Releases vs tags, release workflow anatomy, handling failed releases |
references/phase-4-release-process.md |
Default Posture (No CONTRIBUTING.md)
When a project has no contributing guide, load references/default-posture.md for defensible defaults on issue filing, PRs, communication norms, and code of conduct.
Agent-Specific Checklist
If you are an AI agent filing or contributing on behalf of a human, load references/agent-checklist.md before submitting anything.
Pitfalls
Load references/pitfalls.md when you're about to submit an issue or PR, or when something goes wrong. Covers: backtick expansion, silent label failures, force-push etiquette, the "I'll just fix it quickly" trap, cross-fork PR issues, post-merge scope creep, the installed-code trap, CI debugging, and more.
The Agent-Specific Rule
When filing an issue on behalf of a human, always disclose the agentic nature. Add this line at the bottom of the issue body:
Filed by {{AGENT_NAME}} (AI agent on behalf of {{HUMAN_NAME}})
This is a transparency requirement, not a courtesy. Maintainers deserve to know who they're talking to.
Quick Reference Card
| Step |
Action |
Command / Check |
| 0 |
Read contributing guide |
cat CONTRIBUTING.md or .github/CONTRIBUTING.md |
| 0 |
Check existing issues |
gh issue list --search "topic" --state all |
| 1 |
File a bug/feature |
Use template if provided; include reproduction for bugs |
| 2 |
Issue first before coding |
File issue, wait for maintainer feedback, then branch |
| 3 |
Branch |
git checkout -b fix/description |
| 4 |
Commit |
git commit -s -m "fix: description" |
| 5 |
Run tests locally |
make test or npm test or pytest |
| 6 |
Push |
git push -u origin HEAD |
| 7 |
Open PR |
Fill out PR template completely. Use --body-file for complex bodies |
| 8 |
Monitor CI |
gh pr checks --watch |
| 9 |
Address review |
Respond to comments, push fixup commits. No force-push after review |
| 10 |
After merge |
git checkout main && git pull && git tag vX.Y.Z && git push origin main --tags |
| 11 |
Create Release |
gh release create vX.Y.Z --title "vX.Y.Z — Title" --notes-file /tmp/notes.md |
When NOT to Use This Skill
- You're the sole maintainer of a project with no external contributors and no public collaborators
- You're making a trivial single-line fix to your own code
- The contribution is internal (same organization, same team) with established workflow norms
- You already know the project's contributing guidelines by heart and this is routine
- The issue is a security vulnerability — follow the project's security disclosure policy instead
1---2name: opensource-contributions3description: >-4 Make good open source contributions — check CONTRIBUTING.md first, follow project norms,5 be a good citizen. Covers bug reports, feature requests, and pull requests with a6 defensible default posture when the project hasn't documented expectations. Do not use7 this skill for unrelated requests; route to the nearest named specialist.8license: MIT9compatibility: Compatible with any agent supporting the Agent Skills format (Hermes10 Agent, Claude Code, GitHub Copilot, OpenCode, Cursor, etc.)11metadata:12 source: https://skillmd.com/skills/magnus919/opensource-contributions13 tags: opensource, contributing, github, etiquette, PRs, issues14 related_skills: github-issues, github-pr-workflow, github-code-review15 version: 1.6.016 author: agent-skills17 source_repo: https://agentskills.io18---1920# Open Source Contributions2122## The Golden Rule2324**Make it easy for maintainers to absorb your contribution.** Maintainers are often under-resourced volunteers or small teams. Every friction point you remove — unclear reproduction steps, missing tests, bad commit messages, force-pushed history — is time they don't have to spend figuring out what you did and why. The whole point is to *help* them, not create more work.2526## When to Use This Skill2728- Filing a bug report or feature request on a public repository29- Preparing a pull request for any open source project30- Working on a project without documented contributing guidelines (default posture)31- Reviewing your own PR before submission32- Setting up open source conventions for your own project3334**Load the relevant phase reference for detailed instructions.**3536---3738## Quick Phase Overview3940| Phase | What It Covers | Reference |41|-------|----------------|-----------|42| **0a — Maintainer Conventions** | README discipline, LICENSE, CONTRIBUTING.md, issue/PR templates, commit conventions, DCO, release workflow hygiene | `references/phase-0a-maintainer-conventions.md` |43| **0 — Before You Start** | Reading CONTRIBUTING.md, checking existing issues/PRs, triaging bugfix candidates, large-change discussion etiquette | `references/phase-0-before-you-start.md` |44| **1 — Filing Issues** | Bug report and feature request templates, agent disclosure, maintainer workflow ("issue first"), coordinated multi-issue roadmaps, multi-PR plan execution | `references/phase-1-filing-issues.md` |45| **2 — Pull Requests** | Branching conventions, scope assessment, studying existing implementations, cross-repo comparison, commit messages, PR templates, documentation audits, CI setup | `references/phase-2-pull-requests.md` |46| **3 — After Submitting** | CI monitoring, responding to review feedback, what to do if your PR goes stale or gets closed | `references/phase-3-after-submitting.md` |47| **3.5 — Follow-up After Scope Feedback** | Systematic call-site audits, filing comprehensive issues, complementary PRs when maintainer scope notes identify gaps | `references/phase-35-followup.md` |48| **4 — Release Process** | Version bumping, tagging, GitHub Releases vs tags, release workflow anatomy, handling failed releases | `references/phase-4-release-process.md` |4950### Default Posture (No CONTRIBUTING.md)5152When a project has no contributing guide, load `references/default-posture.md` for defensible defaults on issue filing, PRs, communication norms, and code of conduct.5354### Agent-Specific Checklist5556If you are an AI agent filing or contributing on behalf of a human, load `references/agent-checklist.md` before submitting anything.5758### Pitfalls5960Load `references/pitfalls.md` when you're about to submit an issue or PR, or when something goes wrong. Covers: backtick expansion, silent label failures, force-push etiquette, the "I'll just fix it quickly" trap, cross-fork PR issues, post-merge scope creep, the installed-code trap, CI debugging, and more.6162---6364## The Agent-Specific Rule6566When filing an issue on behalf of a human, **always disclose the agentic nature.** Add this line at the bottom of the issue body:6768```69Filed by {{AGENT_NAME}} (AI agent on behalf of {{HUMAN_NAME}})70```7172This is a transparency requirement, not a courtesy. Maintainers deserve to know who they're talking to.7374---7576## Quick Reference Card7778| Step | Action | Command / Check |79|------|--------|-----------------|80| 0 | Read contributing guide | `cat CONTRIBUTING.md` or `.github/CONTRIBUTING.md` |81| 0 | Check existing issues | `gh issue list --search "topic" --state all` |82| 1 | File a bug/feature | Use template if provided; include reproduction for bugs |83| 2 | Issue first before coding | File issue, wait for maintainer feedback, then branch |84| 3 | Branch | `git checkout -b fix/description` |85| 4 | Commit | `git commit -s -m "fix: description"` |86| 5 | Run tests locally | `make test` or `npm test` or `pytest` |87| 6 | Push | `git push -u origin HEAD` |88| 7 | Open PR | Fill out PR template completely. Use `--body-file` for complex bodies |89| 8 | Monitor CI | `gh pr checks --watch` |90| 9 | Address review | Respond to comments, push fixup commits. No force-push after review |91| 10 | After merge | `git checkout main && git pull && git tag vX.Y.Z && git push origin main --tags` |92| 11 | Create Release | `gh release create vX.Y.Z --title "vX.Y.Z — Title" --notes-file /tmp/notes.md` |9394---9596## When NOT to Use This Skill9798- You're the sole maintainer of a project with no external contributors and no public collaborators99- You're making a trivial single-line fix to your own code100- The contribution is internal (same organization, same team) with established workflow norms101- You already know the project's contributing guidelines by heart and this is routine102- The issue is a security vulnerability — follow the project's security disclosure policy instead