Gr Readme

GitHub README Writing System

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

---

双重视角 / Dual Frame: README Writing = Skill Description Writing

One insight from Claude Code Skills that applies directly to README craft:

> "Claude uses the description field to decide when to apply the skill."

A README's tagline works by exactly the same logic: a one-sentence description that makes the right reader self-select in. If Claude can't tell from your skill's description when to use it, visitors can't tell from your README why they need it.

The table below maps the parallel:

| README element | Skill frontmatter field | Shared principle | |---------------|------------------------|-----------------| | Tagline (first line) | description first sentence | Specific, scannable, triggers the right reader | | Sub-description (2–3 sentences) | description body | Problem + solution + differentiator | | Trigger phrases in README | when_to_use | Disambiguation — when to use this, not something else | | Architecture/How it works | Supporting files (reference.md) | Detail on demand, not always in context | | Quick Start commands | allowed-tools + shell blocks | Concrete, executable, verifiable |

This frame is not a metaphor — it's a practical test. If you can't write a one-sentence tagline for your README that passes the same bar as a skill's description, the README needs more work.

---

核心原则 / Core Principles

Principle 1: README is your product's first landing page

The README has one job: convert a GitHub visitor into a star, fork, or install within 3 seconds of first scroll. Everything else is secondary.

Principle 2: A weak product can still have a great README

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

The README is your narrative. You're selling the vision and the pain point solved, not the current feature set. A product at 30% completion with a clear "why you need this" README will outperform a finished product with a feature dump.

Principle 3: English-first, first screen readable in README 英文主，首屏 — (AFFiNE case, Iris Wei @WeiYipei, ep03)

The first scroll of a GitHub page is ~600–800px. Everything above the fold must answer: What is this? Why does it matter? Who is it for?

Principle 4: Specific, verifiable instructions beat generic claims

From Anthropic prompt engineering and CLAUDE.md effective instructions:

> "Use 2-space indentation" beats "Format code properly." > "Run npm test before committing" beats "Test your changes."

Apply the same test to README copy:

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

Every sentence in a README is an instruction to the reader's brain. Make it concrete enough to verify.

---

README 结构框架 / README Structure Framework

Derived from analysis of insforge (agentic coding backend), dify (60K+ star LLM platform), and AFFiNE's 0→60K growth.

[Logo + Project Name]
[One-line Tagline]              ← most critical, non-skippable
[Badges]                        ← signals, not decoration
[Hero image / Demo video]       ← show product in  Tagline: "Open source Notion alternative"
> 6 words hit 3 pain points: Notion offline unavailable, poor data export, privacy.
> — (Iris Wei @WeiYipei, ep01)

The tagline borrows Notion's brand awareness (no explanation needed), and "alternative" signals open-source + self-hostable + "same features without the things you hate" — all simultaneously.

**Rules:**
- ≤ 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

**Connection to skill design:** This is identical to the `description` field rule from [Skills docs](https://docs.anthropic.com/en/docs/claude-code/skills): "Put the key use case first." The first sentence is truncated in skill listings — and in GitHub search results.

---

### Section 2: Hero Image / Demo Video

**Show before you tell.**

A 30–60 second demo video reduces cognitive load by ~80%. If no video, a high-quality screenshot or GIF showing actual product use is non-negotiable for UI products.

For CLI / SDK tools: a `mermaid` architecture diagram + installation command is the equivalent.

**Rules:**
- 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

---

### Section 3: Quick Start

**This section's only job: get the user to a running instance as fast as possible.**

```bash
# 3–5 commands max. No explanations between commands.
git clone https://github.com/yourorg/yourrepo
cd yourrepo
docker compose up -d
# → open http://localhost:3000

Rules:

• If setup takes >5 commands, the problem is onboarding, not the README
• Prerequisites go above the commands, not buried in a footnote
• Provide a cloud/hosted version link as an alternative — "Don't want to self-host? Try cloud.yourproject.com"
• The commands must actually work on a fresh machine. Test this.

What dify does right: Quick Start is literally the second section after the description. Minimum system requirements (CPU/RAM), then 4 commands. No architecture essay first. Get them running, then explain.

---

Section 4: Key Features

Sort by user pain, not technical implementation.

❌ Wrong (technical list):

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

✅ Right (pain-first):

- 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

Rules:

• ≤ 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

---

Section 5: Architecture / How It Works (Optional)

Include when:

• 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

Rules:

• 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]

---

Section 6: Deployment Options

Address all three developer modes: local dev, self-hosted production, cloud.

| Method | Link | When to use |
|--------|------|-------------|
| Cloud (hosted) | [yourproject.com](link) | Zero setup, try now |
| Docker Compose | [Quick Start](#quick-start) | Self-hosted, recommended |
| Railway / Render | [one-click deploy](link) | Self-hosted, no Docker |
| From source | [Dev Guide](link) | Contributing |

One-click deploy buttons (Railway, Render, Zeabur, Sealos) are high-signal trust indicators and reduce friction to zero for non-Docker users.

---

Section 7: Claude Code / AI Agent Integration ← New Section

Add this section if your project:

• 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

## Claude Code / AI Agent Integration

Install as a skill (Claude Code):
\```
npx skills add your-project-name
\```

Or reference directly in your `CLAUDE.md`:
\```markdown
@your-project/README
\```

For MCP integration:
\```json
{
  "mcpServers": {
    "your-project": {
      "command": "npx",
      "args": ["-y", "@your-org/your-mcp-server"]
    }
  }
}
\```

Why this matters:

• Claude Code skills load from ~/.claude/skills/ or .claude/skills/ — your README is often the first thing the skill system reads to understand what the project does (Skills docs)
• The /run and /verify bundled skills infer launch from your README — a clear Quick Start section directly improves AI agent onboarding
• GEO (Generative Engine Optimization): structured, machine-readable README sections increase the probability that AI systems cite your project accurately

---

Section 8: Contributing

Keep short. Guide lives in CONTRIBUTING.md.

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup.

Questions? Join [Discord](link) or open a [Discussion](link).

Do not put a full contributing guide in the README. It breaks reading flow and buries the CTA in prose.

---

Section 9: Community & Support

Match channel to action type — don't list channels without explaining purpose:

## Community & Support

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

---

Section 10: Star History Chart

Put at the bottom. Social proof, not navigation.

[](https://star-history.com/#yourorg/yourrepo&Date)

A steep upward curve signals "this project is real." Investors use this too.

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

---

Section 11: Star CTA GIF — The Most Underused Conversion Trick

A short GIF showing the mouse clicking the ★ Star button converts passers-by into stargazers. It sounds trivial. It works.

Why it works:

• 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

How to make the GIF (3 options):

| Option | Tool | Time | Quality | |--------|------|------|---------| | Screen record + convert | QuickTime (Mac) + Gifox / LICEcap / ScreenToGif | 5 min | ★★★★ | | Browser extension | Screencastify or Loom → export GIF | 3 min | ★★★ | | Online recorder | Giphy Capture (Mac) | 3 min | ★★★ |

What to record (exact steps):

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

GIF specs:

• 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

Placement in README: First 3 screens, not the bottom

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

Option A — Inline with Hero (recommended): Right after the tagline + badges, before Quick Start. Catches visitors while they’re still deciding whether to care.

## About

Open source Notion alternative. [tagline...]

⭐ **If this looks useful, star it** — it helps others find the project.

Option B — After Quick Start (second-best): After users successfully run the project, strike while the iron is hot.

## Quick Start

```bash
npm install yourproject

It works? ⭐ Star this repo — takes 2 seconds.

**Option C — Star History at the bottom (in addition to A or B, not instead):**

```markdown
## ⭐ Star History

[](https://star-history.com/#yourorg/yourrepo&Date)

Rule: always use A or B. C is optional extra.

Store the GIF in your repo:

yourrepo/
└── assets/
    └── star-demo.gif   ← commit this

Tone guidance:

• ✅ "If this project helped you, a star means a lot"
• ✅ "Star us to stay updated"
• ❌ "PLEASE GIVE US A STAR!!!"
• ❌ "Don’t forget to star!" (implies obligation)

> The GIF does the asking so the text doesn’t have to.

---

Badge 使用原则 / Badge Usage Principles

Badges are signals, not decoration. Each badge answers a developer question.

| Badge type | Question answered | Include? | |-----------|-------------------|----------| | License | "Can I use this commercially?" | Always | | Stars | "Is this popular / maintained?" | Always | | Last commit | "Is this abandoned?" | Yes | | Build / CI status | "Does it actually work?" | Yes | | Downloads (npm/docker/pypi) | "Is anyone actually using this?" | Yes if >1K | | Code coverage | "Is the code quality real?" | Only if >70% | | Version | "What's stable?" | Yes for libraries | | "Made with X" partner badges | — | Omit unless required |

Rules:

• ≤ 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.

---

常见死亡模式 / Anti-patterns (README Death Modes)

❌ Death Mode 1: Feature Dumping Without Problem Framing

Features:
- Real-time collaboration
- Markdown support
- Plugin system
- REST API
- Mobile app
- Dark mode

Tells me nothing about who this is for or why I need it.

Fix: Lead with the pain. "If you've ever lost work because [X happened], MyApp solves that."

---

❌ Death Mode 2: Burying Quick Start

Quick Start below the second scroll = 60% of developers already gone.

Fix: Quick Start is section 2 or 3. Maximum.

---

❌ Death Mode 3: Generic Tagline

A powerful, flexible, and extensible framework for modern developers.

"Powerful," "flexible," "extensible" — every project makes these claims. This is noise.

Fix: Name the specific pain. Name the specific category. Name the specific user.

Prompt engineering parallel: Per Anthropic's guidance, vague instructions ("Format code properly") produce inconsistent results. Same principle: vague taglines produce inconsistent reader behavior.

---

❌ Death Mode 4: No Visual Above the Fold

Wall of text → wall of text → wall of text. Developers scan; they don't read.

Fix: Hero image or demo GIF immediately after the tagline. Non-negotiable for UI products.

---

❌ Death Mode 5: README Only in Native Language

> README 英文主，首屏 — (AFFiNE case, Iris Wei @WeiYipei, ep03)

Chinese-only, Japanese-only README caps addressable audience. GitHub Trending, HN, Reddit — all English-first platforms.

Fix: English is the primary document. Translated versions via badges or /i18n/ folder.

---

❌ Death Mode 6: Contributing Section as Wall of Text

If ## Contributing runs for 400 lines in the README, it's buried in prose and no one reads it.

Fix: One paragraph + link to CONTRIBUTING.md. README is a landing page.

---

❌ Death Mode 7: Treating Stars as Vanity Metrics

Stars are distribution signals. GitHub Trending, search ranking, investor due diligence — all use star velocity as a legitimacy proxy.

> 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 @Wei

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gingiris-1031
• Source: Gingiris-1031/gingiris-skills
• License: MIT

Install and usage instructions live in the source repository linked above.