diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md
index 2b0f867..b131eee 100644
--- a/docs-files-api/SKILL.md
+++ b/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.