From 349c6479e1b3842ddf07e57f2d2d83e01dea4987 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Fri, 9 Oct 2026 01:25:13 -0500 Subject: [PATCH] docs-files-api: two sentences, then getting started, then features Generated-by: Claude Opus 5.5 --- docs-files-api/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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.