supermatt

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.

When a change affects setup, workflows, commands, data handling, or release behavior, update the relevant README, contributor, privacy, glossary, and agent documentation in the same change. Describe capability fallbacks and issue closure consistently with the skills that own them.

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