docs: add README

What's here, and how to add a skill.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

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.

ibis-design/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ibis-design
+description: >-
+  IBIS / issue-based information system — use when writing or reviewing a design discussion, decision record, or outline of issues, positions, and pro/con arguments; when someone marks lines with `?`, `?!`, `?~`, `:`, `:+`, `:-`, `:~+`, `+`, `-`, `!`, `.`; when asked to "IBIS this", lay out options for a decision, record a fallback, or capture why a choice was made. Source: dckc/vattr97 wiki IBIS page.
+---
+
+# IBIS design discussions
+
+[IBIS page on the vattr97 wiki](https://github.com/dckc/vattr97/wiki/IBIS),
+condensed to working rules. See also
+[Issue-based information system on Wikipedia](https://en.wikipedia.org/wiki/Issue-based_information_system).
+
+IBIS develops solutions to issues asynchronously and keeps the
+reasoning around so the resolution can evolve. It's an outline; a
+leading symbol on each item says what kind of element it is.
+
+## symbols
+
+| Symbol | Meaning |
+| :---: | :--- |
+| `?` | an issue to be considered |
+| `?!` | a resolved issue |
+| `?~` | tentatively resolved, or still open but with a fallback position |
+| `:` | a position on an issue (positions on one issue may overlap) |
+| `:+` | an accepted position |
+| `:-` | a rejected position |
+| `:~+` | tentatively accepted, or the fallback position for the issue |
+| `+` | pro: an argument for a position |
+| `-` | con: an argument against a position |
+| `!` | a to-do on an element (optionally with initials: `!jf`) |
+| `.` | a comment on an element |
+
+## rules
+
+1. **Phrase issues to admit overlapping positions**, as complete
+   sentences — not yes/no. "? What tools should we provide for
+   enterprise developers?", not "? Should we support VSCode?"
+2. **Positions are complete sentences** proposing a full or partial
+   solution. They may overlap or conflict, and needn't capture every
+   ramification — refine them with sub-positions.
+3. **Nesting:**
+   - A sub-issue discusses a portion of its outer issue; its positions
+     nest under it.
+   - A sub-position refines its parent *assuming the parent is
+     accepted*; its arguments nest under it.
+   - Arguments are always pro or con with respect to their containing
+     issue, so a `+` under a `-` is typically a mitigation ("here's why
+     that con isn't so bad").
+4. **An issue is resolved only when some position is accepted.** Not
+   every position needs an accept/reject verdict.
+5. **Use fallbacks (`?~`, `:~+`) to agree on a minimum bar** while
+   leaving the issue open. The first fallback is often the status quo.
+   Being the fallback must not preclude considering other options —
+   that's what keeps fallbacks easy to agree on.
+6. **When one issue is really several choices, say so** with a `.`
+   comment and split it into sibling `?` sub-issues.
+
+## writing it in markdown
+
+A leading `-` or `.` collides with list syntax and editor
+auto-bulleting. Put each symbol after the list marker, escaping where
+needed (`- \- con`, `- \+ pro`), or use a fenced block with indentation
+as in the example below.
+
+## example
+
+```
+? How should we test our software?
+  : use a test runner of some form
+  : build a QA department
+  :~+ use tape
+    + it's what we currently use
+    + it's very simple
+    + it works in numerous environments
+      - it's not very expressive
+    - it doesn't have code coverage
+  : use Jest
+    + lots of people like it
+    - guess-my-syntax DSL for expressing assertions
+      + you can separate the assertion choice from the framework
+    + can do integration and unit tests very well
+      !jf can it do them better than tape?
+  : roll our own test runner
+    : make them importable ESM
+      . then we can run them in XS
+      + could be simpler than tape
+      - requires implementation and maintenance
+  :+ use test262
+    + required for JS standards testing
+      - clunky for other uses
+  . there are actually three separate choices: test runner, test environment, and assertion library
+  ? What assertion library should we use?
+  ? What test runner should we use?
+  ? What test environments should we support?
+    : SES
+    : NodeJS
+    : in-browser
+```

io-between-turns/SKILL.md

@@ -47,7 +47,7 @@ paper.)
 
 ## see also
 
-- [ocap-discipline](../ocap-discipline/SKILL.md): who gets to do I/O at
+- [no-ambient-authority](../no-ambient-authority/SKILL.md): who gets to do I/O at
   all (authority passed in, not ambient); this skill is about *when*.
 - [silent-failures-are-evil](../silent-failures-are-evil/SKILL.md): an
   awaited I/O failure still needs a trace.

lazy-tdd/SKILL.md

@@ -46,5 +46,5 @@ amounts", not "fix for goof #3".
 If the goof can't reasonably be captured in an automated test (e.g. it
 lives in config, a one-off script, or untestable I/O with no seam), say
 so explicitly, explain why, and suggest the seam that would make it
-testable (see [ocap-discipline](../ocap-discipline/SKILL.md) for
+testable (see [no-ambient-authority](../no-ambient-authority/SKILL.md) for
 injecting I/O). Don't silently skip the debt.

no-ambient-authority/SKILL.md

@@ -1,6 +1,7 @@
 ---
-name: ocap-discipline
-description: Use when writing or reviewing code whose functions touch I/O, clocks, random number generators, process.env, fetch, or filesystem; when someone says "ambient authority", "wash your mouth out", or "that function shouldn't reach for that"; when debating dependency injection or default-arg seams; when asked what OCap discipline is. Source: the Agoric wiki's OCap Discipline page.
+name: no-ambient-authority
+description: >-
+  Use when writing or reviewing code whose functions touch I/O, clocks, random number generators, process.env, fetch, or filesystem; when someone says "ambient authority", "wash your mouth out", or "that function shouldn't reach for that"; when debating dependency injection or default-arg seams; when asked what OCap discipline is. Source: the Agoric wiki's OCap Discipline page.
 ---
 
 # OCap Discipline
@@ -10,14 +11,22 @@ condensed to working rules.
 
 ## the background, in three lines
 
-Object-capability security = memory safety + encapsulation ("no
+Object-capability security
+([capability-based security](https://en.wikipedia.org/wiki/Capability-based_security))
+= memory safety + encapsulation ("no
 reference to an object except: create it, be given it at creation, or
 receive it in a message") combined with **primitive effects only via
 references** — all world-touching primitives are embodied by objects,
 and *anything globally accessible is immutable data*. No `open(filename)`
 in the global namespace: converting a string to file access is like
-casting an integer to a pointer. JavaScript doesn't enforce this; the
-discipline is a convention (layerable via SES).
+casting an integer to a pointer; that's
+[ambient authority](https://en.wikipedia.org/wiki/Ambient_authority).
+JavaScript doesn't enforce this; the discipline is a convention
+(layerable via SES).
+
+New to object capabilities? Start with
+[awesome-ocap](https://github.com/dckc/awesome-ocap), a curated list of
+capability-based languages, systems, papers, and talks.
 
 ## the working rules (from the wiki)
 
@@ -66,6 +75,8 @@ export const mintKey = (entropy: Entropy): string => b32(entropy(16));
 
 - [OCap Discipline — Agoric wiki](https://github.com/Agoric/agoric-sdk/wiki/OCap-Discipline)
   (Miller, *Robust Composition* PhD thesis, 2006, is the deep source)
-- [ambient authority — Wikipedia](https://en.wikipedia.org/wiki/Ambient_authority)
+- [Ambient authority — Wikipedia](https://en.wikipedia.org/wiki/Ambient_authority)
+- [Capability-based security — Wikipedia](https://en.wikipedia.org/wiki/Capability-based_security)
+- [awesome-ocap: Awesome Object Capabilities and Capability-based Security](https://github.com/dckc/awesome-ocap)
 - in this workspace: `capsite/docs/webkeys.md` (URL-borne bearers),
   Agoric's eslit-based enforcement notes for contracts

silent-failures-are-evil/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: silent-failures-are-evil
-description: No silent failures — use when writing or reviewing error handling: catch blocks, promise rejections, fallbacks for unsupported features, or any branch that treats a result as "didn't work"; when a UI shows a failure with nothing logged; when someone says "silent failure". Every failure path leaves a trace in the logs, and no failure is invented without checking what the API actually returns.
+description: >-
+  No silent failures — use when writing or reviewing error handling: catch blocks, promise rejections, fallbacks for unsupported features, or any branch that treats a result as "didn't work"; when a UI shows a failure with nothing logged; when someone says "silent failure". Every failure path leaves a trace in the logs, and no failure is invented without checking what the API actually returns.
 ---
 
 # Silent failures are evil
@@ -21,7 +22,7 @@ must leave a trace.
 - **Say only what you know.** When an API can't tell you the outcome,
   report what it did tell you ("offered", not "saved").
 - **Make it testable.** Pass the logger in (see
-  [ocap-discipline](../ocap-discipline/SKILL.md)) so a test can assert
+  [no-ambient-authority](../no-ambient-authority/SKILL.md)) so a test can assert
   that the failure path logged; a discovered silent failure is a goof
   that owes a test ([lazy-tdd](../lazy-tdd/SKILL.md)).
 

stop-blathering/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: stop-blathering
+description: >-
+  Stop blathering; be concise, truthful, relevant, clear (Grice's maxims) — use when writing or copy editing prose for a reader (docs, READMEs, skills, commit messages, PR descriptions, replies); when someone says "tighter", "too wordy", "blathering", "omit needless words", or cites Strunk & White or Grice; when about to say something you lack adequate evidence for. Optimize for reader attention: say what's needed, nothing the reader already knows, in an order easy to follow.
+---
+
+# Be concise; optimize for reader attention
+
+Take care to apply [Grice's four maxims](https://en.wikipedia.org/wiki/Cooperative_principle#Grice's_maxims)
+of conversation: quantity, quality, relation, and manner.
+
+The maxim of **quantity** is: be informative.
+
+Submaxims:
+
+- Make your contribution as informative as is required (for the current
+  purposes of the exchange).
+  **Do not make your contribution more informative than is required.**
+
+The maxim of **quality** is: be truthful.
+
+Supermaxim:
+
+- Try to make your contribution one that is true.
+
+Submaxims:
+
+- Do not say what you believe is false.
+- Do not say that for which you **lack adequate evidence**.
+
+The maxim of **relation** is: be relevant: the information provided
+should be relevant to the current exchange and omit any irrelevant
+information. Do not spend words on things the reader already knows.
+
+The maxim of **manner** is: be clear.
+
+Be brief — i.e., avoid unnecessary verbosity.
+Be orderly — i.e., provide information in an order that makes sense,
+and makes it easy for the recipient to process it.
+
+If you can say it with fewer words, do.
+
+## in practice
+
+- Link a well-known convention; don't restate it.
+- Cut tails that repeat a name, a link's target, or the obvious.
+- Quote the key line of a source; explain the rest in your own words.
+
+## sources
+
+- William Strunk Jr., [The Elements of Style](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm)
+  (1918; later editions with E. B. White). Rule 13, "Omit needless words":
+
+  > Vigorous writing is concise. A sentence should contain no unnecessary
+  > words, a paragraph no unnecessary sentences, for the same reason that
+  > a drawing should have no unnecessary lines and a machine no
+  > unnecessary parts.
+
+- Lucile Vaughan Payne,
+  [The Lively Art of Writing](https://openlibrary.org/books/OL7410114M/The_Lively_Art_of_Writing)
+  (Prentice Hall, 1975; ISBN 978-0205091607)
+- [Cooperative principle — Wikipedia](https://en.wikipedia.org/wiki/Cooperative_principle)

yarn-lock-separate-commit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: yarn-lock-separate-commit
-description: yarn.lock in its own commit — use when changing Yarn dependencies (package.json deps, workspace renames, yarn install), when organizing or reviewing commits that touch yarn.lock, when a rebase conflicts on yarn.lock, or during a retcon. Every lockfile change ships alone as `chore: Update yarn.lock`, after the package.json commit that caused it.
+description: >-
+  yarn.lock in its own commit — use when changing Yarn dependencies (package.json deps, workspace renames, yarn install), when organizing or reviewing commits that touch yarn.lock, when a rebase conflicts on yarn.lock, or during a retcon. Every lockfile change ships alone as `chore: Update yarn.lock`, after the package.json commit that caused it.
 ---
 
 # yarn.lock in a separate commit