mad-skills/README.md

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. 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 and opencode see the same set.

writing code

• no-ambient-authority — clocks, RNGs, fetch, and the filesystem come in as parameters.
• io-between-turns — sync I/O is a pointy instrument.
• silent-failures-are-evil — every failure path leaves a trace in the logs.
• lazy-tdd — works the first time? fine. Goofed? You owe a test.
• docs-files-api — 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 — Generated-by: trailers, per the ASF generative tooling guidance.
• retcon — regroup a PR's net diff into clean per-package commits; the merge result doesn't change.
• yarn-lock-separate-commit — yarn.lock changes ship alone.

writing prose

• grice-maxims — say what's needed and no more, only what you can back up, in an order easy to follow.
• hypertext-links — link text says where the link goes; no bare URLs, no "click here".
• citation-needed — back a challenged claim with live links, quoted and dated.
• ibis-design — search a design space: issues, positions, and arguments.

at the terminal

• watchme — I record the session with script -f; read the typescript instead of asking me what happened.
• run-confined — run an untrusted installer in a throwaway systemd user unit that can't see ~/.ssh and friends.
• what-was-i-doing — where did this file come from? Correlate mtimes with git history across every repo.
• notify-me — 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.