Open Source Marketing
When to Use
Use this skill when you need to market an open source project authentically. Trigger phrases include "open source marketing," "OSS marketing," "GitHub marketing," "promote my library," "grow stars," "launch open source," "open source growth," or "contributor marketing.".
This skill helps you market open source projects without being cringe. Covers GitHub optimization, community building, contributor experience, launch strategies, and sustainable growth.
Before You Start
Load your audience context first. Read .agents/developer-audience-context.md to understand:
- Who would use this project (role, tech stack, problem)
- Where they discover tools (communities, social, search)
- What alternatives exist (why would they switch?)
- How they evaluate OSS (stars, activity, docs, community)
If the context file doesn't exist, run the developer-audience-context skill first.
The OSS Marketing Mindset
What Works vs. What Doesn't
| Works |
Doesn't Work |
| Building in public |
Spamming "check out my project" |
| Solving real problems |
Building solutions seeking problems |
| Genuine community engagement |
Transactional follows/unfollows |
| Great docs and DX |
"The code is self-documenting" |
| Celebrating contributors |
Taking sole credit |
| Consistent presence |
Launch and disappear |
The Growth Equation
Growth = (Real value) × (Discoverability) × (First-use experience)
If any factor is zero, growth is zero.
GitHub Optimization
README Excellence
Your README is your landing page. Optimize it.
Structure:
# Project Name
[One-line description that explains what it does]
[Badges: build status, version, license, downloads]
[Screenshot or GIF showing it in action]
## Why [Project Name]?
- ✅ [Benefit 1 - specific, not fluffy]
- ✅ [Benefit 2]
- ✅ [Benefit 3]
## Quick Start
\`\`\`bash
npm install project-name
\`\`\`
\`\`\`javascript
// 5 lines that show immediate value
\`\`\`
## Installation
[Detailed installation for all platforms]
## Usage
[Core usage patterns with examples]
## Documentation
[Link to full docs]
## Contributing
We love contributions! See [CONTRIBUTING.md](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/CONTRIBUTING.md).
## License
[License type] - see [LICENSE](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/LICENSE)
README Checklist
| Element |
Why It Matters |
| Clear name |
Memorable, searchable, spellable |
| One-liner |
"A [type] for [audience] that [does what]" |
| Badges |
Social proof, health signals |
| Visual |
GIF > Screenshot > Nothing |
| Quick start |
<5 lines to first value |
| Why this? |
Differentiation from alternatives |
| Installation |
All platforms, copy-paste |
| Examples |
Real use cases, not contrived |
| Docs link |
More detail available |
| Contributing |
Community welcome |
Repository Optimization
| Element |
Best Practice |
| Description |
100 chars max, keyword-rich |
| Topics |
5-10 relevant tags for discoverability |
| Website |
Link to docs or landing page |
| Releases |
Semantic versioning, changelogs |
| Issues |
Templates for bugs/features |
| Discussions |
Enable for community Q&A |
| Sponsors |
Enable if you want funding |
Issue & PR Templates
Bug report template:
---
name: Bug Report
about: Report a bug to help us improve
---
## Bug Description
[Clear description]
## Steps to Reproduce
1.
2.
3.
## Expected Behavior
[What should happen]
## Actual Behavior
[What actually happens]
## Environment
- OS:
- Node version:
- Package version:
## Additional Context
[Screenshots, logs, etc.]
Feature request template:
---
name: Feature Request
about: Suggest an idea for this project
---
## Problem
[What problem does this solve?]
## Proposed Solution
[How would you like it to work?]
## Alternatives Considered
[Other approaches you've thought about]
## Additional Context
[Examples, mockups, etc.]
Community Building
Community Spaces
| Platform |
Best For |
Setup Effort |
| GitHub Discussions |
Q&A, announcements |
Low |
| Discord |
Real-time chat, community feel |
Medium |
| Slack |
Enterprise communities |
Medium |
| Forum (Discourse) |
Async, searchable discussions |
High |
Start with GitHub Discussions. Add Discord when you have 50+ active users.
Community Principles
| Principle |
Implementation |
| Be responsive |
Respond to issues within 48 hours (even if just "looking into it") |
| Celebrate contributions |
Thank every contributor publicly |
| Be transparent |
Share roadmap, explain decisions |
| Set expectations |
Clear SLA for maintainer response |
| Welcome newcomers |
"good first issue" labels, mentorship |
Contributor Funnel
User → Star → Issue → PR → Regular Contributor → Maintainer
Optimize each transition:
| Transition |
How to Improve |
| User → Star |
Great README, visible value |
| Star → Issue |
Clear issue templates, welcoming tone |
| Issue → PR |
"good first issue" labels, CONTRIBUTING.md |
| PR → Regular |
Quick review, encouraging feedback |
| Regular → Maintainer |
Trust, shared ownership |
Contributor Experience
CONTRIBUTING.md Essentials
# Contributing to [Project]
First off, thanks for considering contributing! ❤️
## Quick Start
1. Fork the repo
2. Clone your fork
3. Install dependencies: `npm install`
4. Create a branch: `git checkout -b my-feature`
5. Make your changes
6. Run tests: `npm test`
7. Commit: `git commit -m "Add my feature"`
8. Push: `git push origin my-feature`
9. Open a Pull Request
## Development Setup
[Detailed setup instructions]
## Code Style
- We use [Prettier/ESLint config]
- Run `npm run lint` before committing
- [Other conventions]
## Commit Messages
We follow [Conventional Commits](https://conventionalcommits.org/):
- `feat: add new feature`
- `fix: resolve bug`
- `docs: update readme`
- `chore: update dependencies`
## Pull Request Process
1. Update docs if needed
2. Add tests for new features
3. Ensure CI passes
4. Get one approval
## Good First Issues
Look for issues labeled `good first issue` — these are great starting points!
## Questions?
Open a Discussion or reach out on Discord.
"Good First Issue" Strategy
Create genuinely approachable issues:
| Good |
Not Good |
| "Add TypeScript types for X function" |
"Refactor the entire codebase" |
| "Fix typo in README" |
"Performance optimization" |
| "Add test for Y method" |
"Debug intermittent CI failure" |
| "Update dependency Z" |
"Implement feature from RFC" |
For each good first issue:
- Explain context and why it matters
- Link to relevant code files
- Describe expected outcome
- Offer to help in comments
Launch Strategies
Pre-Launch Checklist
| Task |
Done? |
| README polished |
☐ |
| Quick start works |
☐ |
| Docs exist |
☐ |
| 3+ examples/demos |
☐ |
| Tests passing |
☐ |
| License chosen |
☐ |
| CONTRIBUTING.md |
☐ |
| Issue templates |
☐ |
| Social preview image |
☐ |
| 5-10 GitHub topics |
☐ |
Launch Day Playbook
Timeline:
| Time |
Action |
| Day before |
Final README review, prep all posts |
| Launch morning |
HN post (best: 6-8am PT, Tuesday-Thursday) |
| +1 hour |
Twitter thread |
| +2 hours |
Reddit post to relevant subreddits |
| Throughout day |
Respond to all comments/questions |
| End of day |
Thank everyone, share metrics |
Platform-Specific Tactics
Hacker News:
- Title: Descriptive, no hype ("Show HN: X — a Y for Z")
- First comment: Explain motivation, tech decisions
- Be available to respond for hours
- Don't ask for upvotes (instant death)
Reddit:
- Find 2-3 relevant subreddits (not just r/programming)
- Read the rules first
- Be a community member, not a marketer
- Share genuinely useful context
Twitter/X:
- Thread format: Problem → Solution → Demo → Link
- Include GIF/video
- Tag relevant accounts (framework authors, etc.)
- Share builds-in-public journey
Dev.to / Hashnode:
- Write a "Why I Built This" article
- Technical depth, personal story
- Cross-post from your blog
Post-Launch
| Week |
Focus |
| Week 1 |
Respond to all feedback, fix bugs |
| Week 2 |
Blog post: "What I learned from launch" |
| Week 3 |
Start regular updates, ship new feature |
| Month 1 |
Community building, contributor docs |
| Ongoing |
Consistent presence, regular releases |
Sustainable Growth
Growth Tactics
| Tactic |
Effort |
Impact |
Timeline |
| SEO-optimized docs |
Medium |
High |
3-6 months |
| Integration tutorials |
Medium |
High |
1-2 months |
| Conference talks |
High |
Medium |
3-6 months |
| Comparison content |
Low |
Medium |
1-2 months |
| Guest blog posts |
Medium |
Medium |
1-2 months |
| Newsletter features |
Low |
Low-Medium |
2-4 weeks |
| Twitter presence |
Medium |
Medium |
Ongoing |
Content Strategy for OSS
| Content Type |
Purpose |
| "Why we built X" |
Launch story, motivation |
| "X vs Y vs Z" |
Capture comparison searches |
| "Migrating from Y to X" |
Convert competitor users |
| "X + [Popular Tool]" |
Capture integration searches |
| "How We Use X at [Company]" |
Social proof, real use case |
| "X Performance Benchmarks" |
Technical credibility |
Avoiding Burnout
| Risk |
Mitigation |
| Overwhelming issues |
Set response SLA expectations |
| Feature demands |
Public roadmap, RFC process |
| Solo maintenance |
Actively recruit co-maintainers |
| Always-on pressure |
Scheduled "office hours" vs. 24/7 |
| Negative feedback |
Code of conduct, moderation |
Metrics That Matter
Vanity vs. Value
| Vanity Metric |
Value Metric |
| Stars |
Active issues + PRs |
| Forks |
Returned contributors |
| Downloads |
Weekly active users |
| Twitter followers |
Community engagement |
What to Track
| Metric |
Where to Find It |
| Stars over time |
GitHub Insights, Star History |
| Clones |
GitHub Traffic |
| Referrers |
GitHub Traffic |
| npm downloads |
npm-stat.com |
| Community size |
Discord/Slack member count |
| Contributor count |
GitHub Insights |
| Issue response time |
Manual tracking |
Tools
| Tool |
Use Case |
| Octolens |
Monitor mentions of your project across GitHub, HN, Reddit, Twitter, and Stack Overflow. Track competitor projects. Find contributors asking questions. |
| Star History |
Track star growth over time |
| npm-stat |
Download statistics |
| GitHub Traffic |
Views, clones, referrers |
| Shield.io |
Dynamic badges |
| All Contributors |
Recognize all contributors |
| Probot |
Automate GitHub workflows |
Related Skills
developer-audience-context — Know who your users are
community-building — Build Discord/Slack community
devrel-content — Create supporting content
developer-advocacy — Conference talks, podcasts
hacker-news-strategy — Launch and engage on HN
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
1---2name: open-source-marketing3description: When the user wants to market an open source project authentically. Trigger phrases include "open source marketing," "OSS marketing," "GitHub marketing," "promote my library," "grow stars," "launch open source," "open source growth," or "contributor marketing."4risk: critical5source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing6source_repo: jonathimer/devmarketing-skills7source_type: community8date_added: 2026-07-019license: MIT10license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE11metadata:12 source: https://skillmd.com/skills/iradoweck/open-source-marketing13---1415# Open Source Marketing16## When to Use1718Use this skill when you need to market an open source project authentically. Trigger phrases include "open source marketing," "OSS marketing," "GitHub marketing," "promote my library," "grow stars," "launch open source," "open source growth," or "contributor marketing.".192021This skill helps you market open source projects without being cringe. Covers GitHub optimization, community building, contributor experience, launch strategies, and sustainable growth.2223---2425## Before You Start2627**Load your audience context first.** Read `.agents/developer-audience-context.md` to understand:2829- Who would use this project (role, tech stack, problem)30- Where they discover tools (communities, social, search)31- What alternatives exist (why would they switch?)32- How they evaluate OSS (stars, activity, docs, community)3334If the context file doesn't exist, run the `developer-audience-context` skill first.3536---3738## The OSS Marketing Mindset3940### What Works vs. What Doesn't4142| Works | Doesn't Work |43|-------|--------------|44| Building in public | Spamming "check out my project" |45| Solving real problems | Building solutions seeking problems |46| Genuine community engagement | Transactional follows/unfollows |47| Great docs and DX | "The code is self-documenting" |48| Celebrating contributors | Taking sole credit |49| Consistent presence | Launch and disappear |5051### The Growth Equation5253```54Growth = (Real value) × (Discoverability) × (First-use experience)55```5657If any factor is zero, growth is zero.5859---6061## GitHub Optimization6263### README Excellence6465Your README is your landing page. Optimize it.6667**Structure:**6869```markdown70# Project Name7172[One-line description that explains what it does]7374[Badges: build status, version, license, downloads]7576[Screenshot or GIF showing it in action]7778## Why [Project Name]?7980- ✅ [Benefit 1 - specific, not fluffy]81- ✅ [Benefit 2]82- ✅ [Benefit 3]8384## Quick Start8586\`\`\`bash87npm install project-name88\`\`\`8990\`\`\`javascript91// 5 lines that show immediate value92\`\`\`9394## Installation9596[Detailed installation for all platforms]9798## Usage99100[Core usage patterns with examples]101102## Documentation103104[Link to full docs]105106## Contributing107108We love contributions! See [CONTRIBUTING.md](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/CONTRIBUTING.md).109110## License111112[License type] - see [LICENSE](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/open-source-marketing/LICENSE)113```114115### README Checklist116117| Element | Why It Matters |118|---------|---------------|119| **Clear name** | Memorable, searchable, spellable |120| **One-liner** | "A [type] for [audience] that [does what]" |121| **Badges** | Social proof, health signals |122| **Visual** | GIF > Screenshot > Nothing |123| **Quick start** | <5 lines to first value |124| **Why this?** | Differentiation from alternatives |125| **Installation** | All platforms, copy-paste |126| **Examples** | Real use cases, not contrived |127| **Docs link** | More detail available |128| **Contributing** | Community welcome |129130### Repository Optimization131132| Element | Best Practice |133|---------|--------------|134| **Description** | 100 chars max, keyword-rich |135| **Topics** | 5-10 relevant tags for discoverability |136| **Website** | Link to docs or landing page |137| **Releases** | Semantic versioning, changelogs |138| **Issues** | Templates for bugs/features |139| **Discussions** | Enable for community Q&A |140| **Sponsors** | Enable if you want funding |141142### Issue & PR Templates143144**Bug report template:**145146```markdown147---148name: Bug Report149about: Report a bug to help us improve150---151152## Bug Description153[Clear description]154155## Steps to Reproduce1561.1572.1583.159160## Expected Behavior161[What should happen]162163## Actual Behavior164[What actually happens]165166## Environment167- OS:168- Node version:169- Package version:170171## Additional Context172[Screenshots, logs, etc.]173```174175**Feature request template:**176177```markdown178---179name: Feature Request180about: Suggest an idea for this project181---182183## Problem184[What problem does this solve?]185186## Proposed Solution187[How would you like it to work?]188189## Alternatives Considered190[Other approaches you've thought about]191192## Additional Context193[Examples, mockups, etc.]194```195196---197198## Community Building199200### Community Spaces201202| Platform | Best For | Setup Effort |203|----------|----------|--------------|204| **GitHub Discussions** | Q&A, announcements | Low |205| **Discord** | Real-time chat, community feel | Medium |206| **Slack** | Enterprise communities | Medium |207| **Forum (Discourse)** | Async, searchable discussions | High |208209Start with GitHub Discussions. Add Discord when you have 50+ active users.210211### Community Principles212213| Principle | Implementation |214|-----------|----------------|215| **Be responsive** | Respond to issues within 48 hours (even if just "looking into it") |216| **Celebrate contributions** | Thank every contributor publicly |217| **Be transparent** | Share roadmap, explain decisions |218| **Set expectations** | Clear SLA for maintainer response |219| **Welcome newcomers** | "good first issue" labels, mentorship |220221### Contributor Funnel222223```224User → Star → Issue → PR → Regular Contributor → Maintainer225```226227Optimize each transition:228229| Transition | How to Improve |230|------------|----------------|231| User → Star | Great README, visible value |232| Star → Issue | Clear issue templates, welcoming tone |233| Issue → PR | "good first issue" labels, CONTRIBUTING.md |234| PR → Regular | Quick review, encouraging feedback |235| Regular → Maintainer | Trust, shared ownership |236237---238239## Contributor Experience240241### CONTRIBUTING.md Essentials242243```markdown244# Contributing to [Project]245246First off, thanks for considering contributing! ❤️247248## Quick Start2492501. Fork the repo2512. Clone your fork2523. Install dependencies: `npm install`2534. Create a branch: `git checkout -b my-feature`2545. Make your changes2556. Run tests: `npm test`2567. Commit: `git commit -m "Add my feature"`2578. Push: `git push origin my-feature`2589. Open a Pull Request259260## Development Setup261262[Detailed setup instructions]263264## Code Style265266- We use [Prettier/ESLint config]267- Run `npm run lint` before committing268- [Other conventions]269270## Commit Messages271272We follow [Conventional Commits](https://conventionalcommits.org/):273- `feat: add new feature`274- `fix: resolve bug`275- `docs: update readme`276- `chore: update dependencies`277278## Pull Request Process2792801. Update docs if needed2812. Add tests for new features2823. Ensure CI passes2834. Get one approval284285## Good First Issues286287Look for issues labeled `good first issue` — these are great starting points!288289## Questions?290291Open a Discussion or reach out on Discord.292```293294### "Good First Issue" Strategy295296Create genuinely approachable issues:297298| Good | Not Good |299|------|----------|300| "Add TypeScript types for X function" | "Refactor the entire codebase" |301| "Fix typo in README" | "Performance optimization" |302| "Add test for Y method" | "Debug intermittent CI failure" |303| "Update dependency Z" | "Implement feature from RFC" |304305For each good first issue:306- Explain context and why it matters307- Link to relevant code files308- Describe expected outcome309- Offer to help in comments310311---312313## Launch Strategies314315### Pre-Launch Checklist316317| Task | Done? |318|------|-------|319| README polished | ☐ |320| Quick start works | ☐ |321| Docs exist | ☐ |322| 3+ examples/demos | ☐ |323| Tests passing | ☐ |324| License chosen | ☐ |325| CONTRIBUTING.md | ☐ |326| Issue templates | ☐ |327| Social preview image | ☐ |328| 5-10 GitHub topics | ☐ |329330### Launch Day Playbook331332**Timeline:**333334| Time | Action |335|------|--------|336| **Day before** | Final README review, prep all posts |337| **Launch morning** | HN post (best: 6-8am PT, Tuesday-Thursday) |338| **+1 hour** | Twitter thread |339| **+2 hours** | Reddit post to relevant subreddits |340| **Throughout day** | Respond to all comments/questions |341| **End of day** | Thank everyone, share metrics |342343### Platform-Specific Tactics344345**Hacker News:**346- Title: Descriptive, no hype ("Show HN: X — a Y for Z")347- First comment: Explain motivation, tech decisions348- Be available to respond for hours349- Don't ask for upvotes (instant death)350351**Reddit:**352- Find 2-3 relevant subreddits (not just r/programming)353- Read the rules first354- Be a community member, not a marketer355- Share genuinely useful context356357**Twitter/X:**358- Thread format: Problem → Solution → Demo → Link359- Include GIF/video360- Tag relevant accounts (framework authors, etc.)361- Share builds-in-public journey362363**Dev.to / Hashnode:**364- Write a "Why I Built This" article365- Technical depth, personal story366- Cross-post from your blog367368### Post-Launch369370| Week | Focus |371|------|-------|372| **Week 1** | Respond to all feedback, fix bugs |373| **Week 2** | Blog post: "What I learned from launch" |374| **Week 3** | Start regular updates, ship new feature |375| **Month 1** | Community building, contributor docs |376| **Ongoing** | Consistent presence, regular releases |377378---379380## Sustainable Growth381382### Growth Tactics383384| Tactic | Effort | Impact | Timeline |385|--------|--------|--------|----------|386| **SEO-optimized docs** | Medium | High | 3-6 months |387| **Integration tutorials** | Medium | High | 1-2 months |388| **Conference talks** | High | Medium | 3-6 months |389| **Comparison content** | Low | Medium | 1-2 months |390| **Guest blog posts** | Medium | Medium | 1-2 months |391| **Newsletter features** | Low | Low-Medium | 2-4 weeks |392| **Twitter presence** | Medium | Medium | Ongoing |393394### Content Strategy for OSS395396| Content Type | Purpose |397|--------------|---------|398| **"Why we built X"** | Launch story, motivation |399| **"X vs Y vs Z"** | Capture comparison searches |400| **"Migrating from Y to X"** | Convert competitor users |401| **"X + [Popular Tool]"** | Capture integration searches |402| **"How We Use X at [Company]"** | Social proof, real use case |403| **"X Performance Benchmarks"** | Technical credibility |404405### Avoiding Burnout406407| Risk | Mitigation |408|------|------------|409| **Overwhelming issues** | Set response SLA expectations |410| **Feature demands** | Public roadmap, RFC process |411| **Solo maintenance** | Actively recruit co-maintainers |412| **Always-on pressure** | Scheduled "office hours" vs. 24/7 |413| **Negative feedback** | Code of conduct, moderation |414415---416417## Metrics That Matter418419### Vanity vs. Value420421| Vanity Metric | Value Metric |422|---------------|--------------|423| Stars | Active issues + PRs |424| Forks | Returned contributors |425| Downloads | Weekly active users |426| Twitter followers | Community engagement |427428### What to Track429430| Metric | Where to Find It |431|--------|------------------|432| **Stars over time** | GitHub Insights, Star History |433| **Clones** | GitHub Traffic |434| **Referrers** | GitHub Traffic |435| **npm downloads** | npm-stat.com |436| **Community size** | Discord/Slack member count |437| **Contributor count** | GitHub Insights |438| **Issue response time** | Manual tracking |439440---441442## Tools443444| Tool | Use Case |445|------|----------|446| **[Octolens](https://octolens.com)** | Monitor mentions of your project across GitHub, HN, Reddit, Twitter, and Stack Overflow. Track competitor projects. Find contributors asking questions. |447| **Star History** | Track star growth over time |448| **npm-stat** | Download statistics |449| **GitHub Traffic** | Views, clones, referrers |450| **Shield.io** | Dynamic badges |451| **All Contributors** | Recognize all contributors |452| **Probot** | Automate GitHub workflows |453454---455456## Related Skills457458- `developer-audience-context` — Know who your users are459- `community-building` — Build Discord/Slack community460- `devrel-content` — Create supporting content461- `developer-advocacy` — Conference talks, podcasts462- `hacker-news-strategy` — Launch and engage on HN463464## Limitations465466- Use this skill only when the task clearly matches its upstream source and local project context.467- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.468- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.