open-source-marketing – Marketing & SEO skill for AI agents

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.

---

Plans and draft posts do not authorize publishing, tagging people, messaging contributors or changing repository settings. Use the user’s approved account/channel and scope for external actions. Treat launch timing, growth impact/time estimates and funnel stages as hypotheses; users need not star or contribute to be successful. Preserve contributor attribution and verify licenses, badges and benchmark claims. Download/clone counts are operations, not unique active users. Named tools are examples; verify current features/costs before choosing a service.

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)

This is a planning metaphor, not a measured growth formula.

---

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 the project’s `CONTRIBUTING.md` (replace with a verified project link when publishing).

## License

[License type] - see the project’s `LICENSE` (replace with a verified project link when publishing).

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 a chat space only when user needs and moderation capacity justify it.

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 at a time you can support; test timing with your audience |

| +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-

… (full content is in the download package)