Built from taking AFFiNE from 0 to 60K stars. The README didn't just describe the product — it was the product for the first 30 days.

— (AFFiNE case, Iris Wei @WeiYipei, ep01/ep03/ep06)

"Claude uses the

description

field to decide when to apply the skill."

description

description

when_to_use

reference.md

allowed-tools

description

AFFiNE 开源时产品还是「套壳」demo，README 写对了照样火。 — (AFFiNE case, Iris Wei @WeiYipei, ep03/ep06)

README 英文主，首屏 <3 秒读懂。 — (AFFiNE case, Iris Wei @WeiYipei, ep03)

"Use 2-space indentation" beats "Format code properly." "Run

npm test

before committing" beats "Test your changes."

• "Works offline — no internet required, all data stored locally" ✅
• "Powerful offline support" ❌

1. Names what the product is (category)
2. Names who it's for (audience)
3. Names the pain it kills (problem)

[Adjective] [category] for [audience]
→ "Open-source backend platform for AI coding agents"

[Category] without [pain point]
→ "Note-taking without the cloud lock-in"

[Familiar reference] + [key differentiator]
→ "Open source Notion alternative — offline-first, privacy-focused"

[Outcome verb phrase]
→ "Ship full-stack apps from your AI agent, end to end"

Tagline: "Open source Notion alternative" 6 words hit 3 pain points: Notion offline unavailable, poor data export, privacy. — (Iris Wei @WeiYipei, ep01)

• ≤ 12 words
• No jargon requiring prior knowledge of your project
• Must work without context — imagine someone sees only this one line
• Never start with "A powerful..." or "An amazing..." — these signal the writer doesn't know what makes the product special

description

mermaid

• Video ≤ 60 seconds, captioned (non-English speakers are a large part of your audience)
• Screenshot shows product in use, not empty state
• Host on GitHub's own CDN — drag into the issue editor, not external CDN
• Dark and light mode variants if supported

- WebSocket support
- Plugin architecture
- REST API
- TypeScript SDK

- Works offline — no internet required, all data stored locally
- Export everything — Markdown, PDF, raw JSON, always your data
- Self-hostable — deploy to your own server in 5 minutes
- Plugin API — extend with your own tools

• ≤ 7 features in the main list. More than 7 signals "we don't know what we are."
• Each bullet: pain point first, implementation detail second
• Bold the key word — GitHub renders bold in feature lists; it's free hierarchy
• If star count is high, mention it implicitly ("used by X developers") — social proof in the features section

• Project has non-obvious component structure (backend platform, distributed system)
• Developers need to understand architecture to decide whether to contribute
• Targeting developers who will integrate, not just use

• Use

  mermaid

  — renders natively on GitHub. One diagram = 200 words.
• Keep the diagram to ≤ 8 nodes
• Put this section after Quick Start

graph TD
    A[User / AI Agent] --> B[Your Product Core]
    B --> C[Service A]
    B --> D[Service B]
    B --> E[Service C]

• Can be used as a Claude Code skill or MCP plugin
• Has a CLI that AI agents can invoke
• Exposes an API that agentic workflows call

undefined

• Discord — questions, help, show what you built
• GitHub Discussions — feature requests, long-form questions
• GitHub Issues — bugs only
• X / Twitter — announcements, follow for updates
• Email — security issues, enterprise inquiries

---

[![Star History Chart](https://api.star-history.com/svg?repos=yourorg/yourrepo&type=Date)](https://star-history.com/#yourorg/yourrepo&Date)

投资人专门写爬虫查 Star 真假，说明真实口碑就是你最有力的信号。 — (AFFiNE case, Iris Wei @WeiYipei, ep03)

• Removes ambiguity: many first-time visitors don’t know where to click to star
• Creates micro-commitment: watching the animation primes the action
• Feels human, not spammy — unlike a bold "PLEASE STAR US" text block

1. Open your repo in browser, zoom to 125%
2. Slowly move mouse to the ★ Star button (top right area)
3. Pause 1 second
4. Click — let the animation play (star turns yellow)
5. Total duration: 3–5 seconds, loop seamlessly

• Size: 400–600px wide, auto height
• Duration: 3–5 seconds, looping
• File size: keep under 1MB (GitHub CDN limit for smooth load)
• Optimize with Ezgif if over 1MB

❗️ Most repos bury the star CTA at the bottom. By then, 80%+ of visitors have already left. Put it where people actually see it.

undefined

• ≤ 8 badges on the first row. More = visual noise.
• Group by meaning: identity → health → community
• Never use a failing badge. A red CI badge is worse than no CI badge.

README 英文主，首屏 <3 秒读懂。 — (AFFiNE case, Iris Wei @WeiYipei, ep03)

/i18n/

AFFiNE hit 6K stars in week 1, 10K in month 1, 60K+ total. 28 consecutive GitHub Trending appearances, driven by two weeks of obsessive community engagement. — (Iris Wei @WeiYipei, ep01/ep06)

• Logo / project name visible and clear
• Tagline ≤ 12 words, answers: what + who + pain
• Hero image, GIF, or demo video within first screen
• Badge row present, ≤ 8 badges
• No wall of text before any visual element

• Quick Start is in the top 3 sections
• Quick Start has ≤ 5 commands and works on a fresh machine
• Features sorted by user pain, not technical implementation
• Each feature bullet leads with benefit, not mechanism
• Contributing section ≤ 1 paragraph + link to CONTRIBUTING.md

• Primary language is English
• No "powerful," "flexible," "amazing," "robust" — replace with specifics
• No "we believe in open source" preamble — cut to the point
• Tagline does not start with "A" or "An"

• License badge present
• CI / build status badge present and passing
• Star history chart at the bottom
• Star CTA GIF in first 3 screens (assets/star-demo.gif, <1MB, 3–5s loop) — NOT at the bottom
• Discord / community link in the README
• If star count >500, visible in badges

• All links tested (no 404s)
• Images hosted on GitHub CDN (not external)

• mermaid

  diagrams render correctly in GitHub preview
• One-click deploy buttons tested (if applicable)
• README renders correctly on mobile (check GitHub mobile)

• skill-ready: Is there a clear

  npx skills add

  or MCP install command?
• GEO-ready: Does the README have structured, machine-readable sections (tables, headers, code blocks) that AI systems can cite accurately?
• Agent-friendly Quick Start: Can Claude Code's

  /run

  skill infer the launch command from your README without a custom skill setup?

README visit → install/start → first successful outcome → return

1. Read only the first screen (simulate no scroll). What do you know about the product? Who it's for? Why it matters? If you can't answer all three, the tagline or hero section needs rewriting.
2. Find Quick Start. Count which section number it is. If ≥ 5, it needs to move up.
3. Read the tagline aloud. Does it sound like a human pitch, or a feature list? If the latter, rewrite using the pain-first formula.
4. Count the features. If >7 bullets, ask: which 3 make someone install this? Keep those, cut the rest.
5. Look for walls of text. Any paragraph >5 lines above the Contributing section is probably explaining something a diagram or demo does better.
6. Check language. Is the primary language English?
7. Check AI integration. Is there a Claude Code / AI agent section? Does the Quick Start work for automated install? (New in 2025.)

• Skills — frontmatter spec, context:fork, allowed-tools, when_to_use
• Memory — CLAUDE.md 4-layer scope, effective instructions, specificity rules
• Prompt engineering overview
• Claude Code documentation home
• Subagents

• Claude Code 101 (SkillJar)
• Prompt Engineering Interactive Tutorial
• Anthropic Academy

• Be specific and direct
• Use XML tags

• Anthropic Discord
• Claude Code GitHub Discussions

• AFFiNE — 0→60K stars case study (primary reference)
• Dify — 60K+ star LLM platform, aggressive Quick Start placement
• InsForge — agentic coding backend, clean tagline + mermaid architecture

gr-oss-marketing

gingiris-opensource