diff --git a/README.md b/README.md
index 5658294..1a9384c 100644
--- a/README.md
+++ b/README.md
@@ -22,8 +22,9 @@ Code](https://code.claude.com/docs/en/skills) and
   failure path leaves a trace in the logs.
 - [lazy-tdd](lazy-tdd/SKILL.md) — works the first time? fine. Goofed?
   You owe a test.
-- [docs-files-api](docs-files-api/SKILL.md) — exported API docs over
-  file docs. Avoid chit-chat.
+- [docs-files-api](docs-files-api/SKILL.md) — README sells and gets
+  you to TADA; CONTRIBUTING has the rest; AGENTS.md links to it.
+  Exported API docs over file docs. Avoid chit-chat.
 
 ## commits and PRs
 
diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md
index 34a2a36..2b0f867 100644
--- a/docs-files-api/SKILL.md
+++ b/docs-files-api/SKILL.md
@@ -1,10 +1,31 @@
 ---
 name: docs-files-api
-description: JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc).
+description: Where docs go — README vs CONTRIBUTING vs AGENTS.md, and JSDoc placement — use when writing or reviewing a README, CONTRIBUTING, or AGENTS.md/CLAUDE.md; when someone asks "how do I run it?" and there's no README; when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc).
 ---
 
 # Documentation Conventions
 
+## README, CONTRIBUTING, AGENTS.md
+
+A **README** does two jobs, in this order:
+
+- **Marketing:** why should the reader care? What's cool about this?
+  A few lines, not a feature matrix.
+- **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.
+
+Everything else goes in **CONTRIBUTING**: design, layout of the code,
+how to test, conventions, deploying.
+
+**AGENTS.md is a symlink to CONTRIBUTING.md** (likewise CLAUDE.md, if a
+tool wants one). Good advice is good advice, for people and bots alike.
+If agents need something people don't, give it a short section in
+CONTRIBUTING.
+
+## JSDoc
+
 JSDoc placement rules (from the
 [portfolio-contract contributing notes](https://github.com/Agoric/agoric-sdk/blob/master/packages/portfolio-contract/CONTRIBUTING.md#documentation-conventions)):