diff --git a/README.md b/README.md
new file mode 100644
index 0000000..682508e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# mad skills
+
+How I like code written, reviewed, and committed — written down so the
+bots I pair with can pick it up without me repeating myself.
+
+These are [Agent Skills](https://agentskills.io/specification). Each
+`description` front-loads the words that should trigger it — the things
+I actually say, like "retcon", "watch me", or "citation needed".
+
+I keep this repo checked out at `.agents/skills/` in a workspace and
+symlink `.claude/skills` and `.opencode/skills` to it, so [Claude
+Code](https://code.claude.com/docs/en/skills) and
+[opencode](https://opencode.ai/docs/skills/) see the same set.
+
+## writing code
+
+- [no-ambient-authority](no-ambient-authority/SKILL.md) — clocks,
+  RNGs, `fetch`, and the filesystem come in as parameters.
+- [io-between-turns](io-between-turns/SKILL.md) — sync I/O is a pointy
+  instrument.
+- [silent-failures-are-evil](silent-failures-are-evil/SKILL.md) — every
+  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.
+
+## commits and PRs
+
+- [disclose-gen-ai](disclose-gen-ai/SKILL.md) — `Generated-by:`
+  trailers, per the ASF generative tooling guidance.
+- [retcon](retcon/SKILL.md) — regroup a PR's net diff into clean
+  per-package commits; the merge result doesn't change.
+- [yarn-lock-separate-commit](yarn-lock-separate-commit/SKILL.md) —
+  `yarn.lock` changes ship alone.
+
+## writing prose
+
+- [stop-blathering](stop-blathering/SKILL.md) — omit needless words.
+- [hypertext-links](hypertext-links/SKILL.md) — link text says where
+  the link goes; no bare URLs, no "click here".
+- [citation-needed](citation-needed/SKILL.md) — back a challenged claim
+  with live links, quoted and dated.
+- [ibis-design](ibis-design/SKILL.md) — search a design space:
+  issues, positions, and arguments.
+
+## at the terminal
+
+- [watchme](watchme/SKILL.md) — I record the session with `script -f`;
+  read the typescript instead of asking me what happened.
+- [run-confined](run-confined/SKILL.md) — run an untrusted installer in
+  a throwaway systemd user unit that can't see `~/.ssh` and friends.
+- [what-was-i-doing](what-was-i-doing/SKILL.md) — where did this file
+  come from? Correlate mtimes with git history across every repo.
+
+## adding one
+
+Name the directory for the trigger, not the topic. Write the
+`description` for the matcher: what I'd say, what I'd be doing, and
+what it's *not* for. Cite the source; quote the key line; explain the
+rest.