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](https://docs.anthropic.com/en/docs/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 o...