docs-files-api: two sentences, then getting started, then features

Generated-by: Claude Opus 5.5

docs-files-api/SKILL.md

@@ -7,14 +7,15 @@ description: Where docs go — README vs CONTRIBUTING vs AGENTS.md, and JSDoc pl
 
 ## README, CONTRIBUTING, AGENTS.md
 
-A **README** does two jobs, in this order:
+A **README** sells, then gets the reader running:
 
-- **Marketing:** why should the reader care? What's cool about this?
-  A few lines, not a feature matrix.
+- **Up top, about two sentences:** what it is and why to care. Then
+  straight to getting started.
 - **Getting started:** get them to TADA! with no fuss. Readers skip to
   the first fenced block and copy it; if it doesn't work, boo. So that
   block runs as-is from a fresh clone and ends with something to look
   at (a URL, output). No architecture, no principles.
+- **After that:** features and benefits, as much as earns its place.
 
 Everything else goes in **CONTRIBUTING**: design, layout of the code,
 how to test, conventions, deploying.