open-source-marketing

Open Source 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](CONTRIBUTING.md).

## License

[License type] - see [LICENSE](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