AGENTS.md git:20261018.b37208bA

Immutable. This exact content never changes and is served at /api/v1/blob/f5e9392aa81ba88c.

Each skill is a directory directly under `skills/` (`skills/<name>/SKILL.md`), never nested deeper: Codex rejects nested skills, and Claude Code, Cursor, and OMP ship the same canonical tree. The plugin ships every skill in `skills/`.

Every skill must have an entry in the top-level `README.md`, under **Engineering** (daily code work) or **Productivity** (daily non-code workflow tools), that links the skill name to its `SKILL.md`. Each section groups its entries into **User-invoked** and **Model-invoked**.

Every `SKILL.md` is either user-invoked (`disable-model-invocation: true` plus `policy.allow_implicit_invocation: false` in `agents/openai.yaml`) or model-invoked. Claude Code, Codex, and Cursor enforce explicit-only metadata; OMP catalog hiding is not an authorization boundary. See [.agents/invocation.md](./.agents/invocation.md) and [references/harnesses.md](./references/harnesses.md).

Any skill change must preserve the Claude Code, Codex, Cursor, and OMP implications in the harness contract: human invocation syntax, model-side composition, capability fallbacks, active-model family resolution, and honest reporting of unavailable independence. Do not infer model family from the harness name.

[`ask-supermatt`](./skills/ask-supermatt/SKILL.md) is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read `ask-supermatt`'s `SKILL.md` and update it so the map stays accurate: a new skill it never mentions, or a stale one it still routes to, is a router that lies.

Record every change to a shipped skill under **Unreleased** in `CHANGELOG.md`. Ordinary fixes and features keep the plugin version unchanged and their notes under Unreleased. The maintainer decides when to cut a release: only an explicit release request authorizes a version bump, dated release notes, a tag, or publication. Committing, pushing, and merging ordinary changes do not authorize a release. The Claude manifest holds the only `version`: the Claude Code catalog (`.claude-plugin/marketplace.json`), Codex catalog (`.agents/plugins/marketplace.json`), and Cursor manifest (`.cursor-plugin/plugin.json`) must not set one. The Claude Code and Codex catalogs must list the same plugins.

For an explicitly requested release, bump `version` in `.claude-plugin/plugin.json` (semver: PATCH for fixes, MINOR for new skills or features, MAJOR for removals or renames; before 1.0.0, a removal or rename bumps MINOR) through a pull request. Once that release PR merges, run `scripts/release.sh` on an up-to-date `main`. It creates the signed `v<version>` tag, pushes it, opens a GitHub Release from that version's `CHANGELOG.md` section, and pushes the release to the `directory` branch. The released plugin directory tracks that branch and holds each release without `scripts/`, `tests/`, and `.github/`: never commit to it by hand. Only the maintainer's account can create `v*` tags: an agent that cannot run it (another account, a denied tool call) hands the maintainer `sh scripts/release.sh` to run instead of stopping at the merge.

When preparing that requested release, move the Unreleased entries into a dated `## [X.Y.Z]` section of `CHANGELOG.md` and add its compare link in the version-bump PR, since that section becomes the GitHub Release notes and `scripts/release.sh` refuses a version without one.

Deprecate a user-reachable skill before you remove or rename it. Ship one release where the old name still works as a stub `SKILL.md` that names the replacement and the version that removes the stub, and list it under **Deprecated** in `CHANGELOG.md`. Remove the stub in a later release and list it under **Removed**.

The `CHANGELOG.md` Unreleased section keeps one entry per skill: fold a new change to a skill into that skill's existing entry instead of adding another line, so the changelog stays compact.

To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill. The script only links current skills. After a removal or rename, inspect the old links and retire only confirmed stale symlinks whose targets belong to this checkout. Leave unrelated links intact; the maintainer-only linker stays unchanged.

No em-dashes anywhere in this repo's prose (`SKILL.md` files, docs, `README.md`, `CHANGELOG.md`, ADRs, changesets, code comments). Where a sentence reaches for one, rewrite it instead with a comma, colon, period, parentheses, or a conjunction, whichever the sentence actually wants; never do a blind character substitution.