feat(obsidian-markdown): add skill

Generated-by: Claude Opus 5.5

README.md

@@ -0,0 +1,68 @@
+# 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) — 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
+
+- [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
+
+- [grice-maxims](grice-maxims/SKILL.md) — say what's needed and no
+  more, only what you can back up, in an order easy to follow.
+- [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.
+- [obsidian-markdown](obsidian-markdown/SKILL.md) — the workspace is
+  an Obsidian vault: one line per paragraph, relative links, no file
+  symlinks you expect Obsidian to show.
+
+## 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.
+- [notify-me](notify-me/SKILL.md) — desktop notification at the end
+  of a long turn, sticky if I'm stepping away; not every reply.
+
+## 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.

docs-files-api/SKILL.md

@@ -1,10 +1,38 @@
 ---
 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** sells, then gets the reader running:
+
+- **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.
+
+**Headings say something.** A heading is prime real estate: it shows in
+the outline and in link targets. "What's in it", "Overview", "Features",
+"Details" say nothing; name the point instead ("Bookmarks in, a zine
+out"). Plain labels are fine only where the reader hunts for them by
+name: "Getting started", "Deploying".
+
+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)):
 

grice-maxims/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: grice-maxims
+description: >-
+  Grice's maxims: be concise, truthful, relevant, clear — use before any reply, and when writing or copy editing prose for a reader (docs, READMEs, skills, commit messages, PR descriptions); when someone says "tighter", "too wordy", "stop 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)

ibis-design/SKILL.md

@@ -0,0 +1,121 @@
+---
+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.
+7. **Attach each argument to the position it bears on.** If it applies
+   equally to the siblings, it belongs higher up, or the issue is
+   several choices (rule 6). A comment that rules a position out is a
+   con, and the position is rejected (`:-`).
+8. **Check the source before raising an issue.** If the design text
+   already answers it, record the issue as resolved and cite that text
+   as the pro.
+9. **Past three levels of nesting, split out a sub-issue.**
+
+## numbering
+
+Number elements so replies can refer to them ("2: …"): issues `1`,
+`2`; positions under them `1a`, `1b`; anything below that `1a-i`,
+`1a-ii`, then `1a-i-a`. The number follows the symbol: `?! 2. …`,
+`:+ 2c. …`. Renumbering breaks references made in chat or other docs,
+so append rather than renumber once people are citing numbers. Show
+dependencies between issues with "(see 5)".
+
+## 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.
+
+Past a screenful, give each top-level issue its own heading
+(`### ? 3. What is the fence?`) with its elements in a fenced block
+below. Headings show up in the editor outline and give each issue a
+link target. Links don't render inside a fence, so put sources after
+the block and refer to them from the line they support.
+
+## 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

notify-me/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: notify-me
+description: Notify me / ping me — desktop (XDG) notification via `notify-send` at the end of any long turn (many steps, builds, test runs, deploys, waiting on background work), asked or not; and when the operator says "notify me", "XDG notify me", "ping me when you're done", "let me know about progress", or "make it stick / indefinite duration" because they're stepping away. Covers done vs. progress notices, sticky vs. transient, and updating one notice in place. Not for Discord replies (use the reply tool) or for quick back-and-forth turns.
+---
+
+# Notify me
+
+```sh
+notify-send -a capsite "done: diigo-cache" "3 commits on main, not pushed"
+```
+
+## Context
+
+The operator hands a session a batch of work, then turns to another session or goes for a walk.
+
+## Problem
+
+**Without going to look, the operator can't tell which session is done or stuck.**
+
+## Forces
+
+- opencode-web notifies on every reply; notices without news teach the operator to ignore them all.
+- Silence is worse: a finished turn sits unseen.
+- The operator won't always think to ask.
+- Notices expire before the operator is back from a walk.
+- Several sessions share one desktop.
+- Progress notices pile up.
+
+## Therefore
+
+**At the end of any turn long enough that the operator has probably looked away, send one notice: which session, what state, what the operator should do next. Not during quick back-and-forth.**
+
+Long means more than a handful of tool calls, or waiting on a build, tests, deploy, or background job. "Notify me when you're done" forces one even for a short turn.
+
+- `-a` names the session (repo or task).
+- The summary leads with the status: `done`, `blocked` (including a question that stops the work), `failed`, `progress`.
+- The body says what's next: "needs a decision on the DO migration".
+
+**Sticky** ("indefinite duration", "going for a walk"): `-t 0` (never expire). `-u critical` only if asked.
+
+**Progress** ("notify me about progress"): one per milestone (tests pass, deployed), replacing the last rather than stacking:
+
+```sh
+id=$(notify-send -p -a capsite "progress: diigo-cache" "tests pass; deploying")
+notify-send -r "$id" -a capsite "done: diigo-cache" "deployed; not pushed"
+```
+
+Keep `$id` in a file (e.g. `.tmp/notify-id`) if the shell doesn't persist.
+
+## Resulting context
+
+The operator can leave a session alone and trust it to call. A notice means news, so it gets read.
+
+`notify-send` needs the session bus; under a confined unit or ssh it may fail. Say so in the reply ([silent-failures-are-evil](../silent-failures-are-evil/SKILL.md)).
+
+The agent must still remember this pattern at the end of a long turn, just when that slips.
+
+## TODO
+
+- A Claude Code `Stop` hook could time the turn and notify past ~2 min; opencode would need its own plugin hook.

obsidian-markdown/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: obsidian-markdown
+description: Markdown in an Obsidian vault that agents also write — use when an agent writes or edits any .md file in a workspace with a `.obsidian/` folder (notes, READMEs, CONTRIBUTING, AGENTS.md, skills, docs); when someone mentions Obsidian, hard wrap, ragged "poetry" margins, wikilinks, or the vault; when adding a symlink to markdown. Not for Discord or PR text (see grice-maxims).
+---
+
+# Markdown for an Obsidian vault agents write in
+
+The workspace is an [Obsidian](https://obsidian.md/) vault: a `.obsidian/` folder at its root. Dan reads and edits in Obsidian; agents write the same files from a terminal. Write markdown that reads well in Obsidian and on GitHub, and is easy for an agent to edit.
+
+## One line per paragraph
+
+Don't hard-wrap prose. A paragraph is one line; so is each list item. Break lines only between blocks: paragraphs, list items, headings, fences.
+
+Wrapped paragraphs render with a ragged "poetry" margin in Dan's Obsidian, and they make diffs of a one-word edit reflow a whole paragraph. Code blocks keep their line breaks, of course.
+
+When you rewrite a wrapped paragraph, unwrap it. Don't unwrap a whole file you aren't otherwise rewriting: that's a noisy diff in someone else's prose.
+
+## Links
+
+- Standard markdown links with relative paths: `[the webkeys pattern](docs/webkeys.md)`. Obsidian follows them, and GitHub renders them. `[[wikilinks]]` render only in Obsidian.
+- No spaces in file names, so links need no `%20`.
+- Link text says where the link goes (see hypertext-links).
+
+## File names and headings
+
+Obsidian shows file names in tabs, the file explorer, and search, so name files for what's in them.
+
+Headings show in Obsidian's outline pane: make them say something.
+
+## Frontmatter
+
+Obsidian shows YAML frontmatter as Properties. Keep it valid YAML: quote values that contain `: ` or start with a special character.
+
+## Symlinks
+
+From [Obsidian's symlinks page](https://obsidian.md/help/symlinks):
+
+> Obsidian ignores any symlink to a parent folder of the vault, or from one folder in the vault to another folder in the same vault.
+
+> File symlinks (as opposed to folder symlinks) may work, but aren't officially supported at this time.
+
+So a folder symlink inside the vault (`.claude/skills` → `.agents/skills`) is invisible to Obsidian, and that's fine: no duplicates. A file symlink like `AGENTS.md` → `CONTRIBUTING.md` may not show or update in Obsidian. Edit the target, never the link.

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)).
 

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