Publish an agent compatibility matrix backed by adapter contract tests

.gitattributes

@@ -0,0 +1,3 @@
+# The adapter contract tests compare these files byte for byte (and hash them
+# for docs/compatibility.md), so never convert their line endings on checkout.
+tests/fixtures/adapter-contracts/** -text

CHANGELOG.md

@@ -149,6 +149,10 @@ All notable changes to this project are documented here. The format is based on
 
 ### Changed
 
+- Asking an adapter for a scope it doesn't support now tells you what works
+  instead (#79). For example, `--agent cursor-rule --scope global` names
+  `--scope project`. On `install` it also names `--agent cursor`, which
+  supports `--scope global`.
 - `meta.yaml` rejects keys other than `name`, `description`, `category`,
   `version`, `supported-agents` and `deprecated`, so a misspelt field fails
   loudly instead of being ignored (#77).
@@ -512,6 +516,30 @@ All notable changes to this project are documented here. The format is based on
 
 ### Added
 
+- Agent compatibility matrix, `docs/compatibility.md` (#79), linked from the
+  README and `docs/adapters.md`. It lists every adapter, including the
+  `copilot-prompt`, `cursor-rule` and `kiro-steering` legacy adapters, with:
+
+  - a status (tested, supported or experimental; the page defines each)
+  - project and global paths, and the environment variables that move them
+  - how you invoke the skill in that agent
+  - the minimum agent version
+  - the date, agent version and vendor sources it was checked against
+
+  Whatever couldn't be checked is marked unverified. The page also says how
+  skilldeck responds when a vendor deprecates or moves a skill location or
+  format.
+
+  Adapter contract fixtures (`tests/fixtures/adapter-contracts/`, contract
+  `sha256:25b3bbad35d7`) pin each adapter's exact rendered file, stamp included, for
+  one synthetic skill. They also pin its project and global paths, and its
+  behaviour with each config-directory variable set to an absolute path,
+  left empty, or set to a relative path. CI installs with every adapter and
+  compares the results byte for byte. It also checks the matrix's path,
+  "Moved by" and scope-error text against the contracts. A test fails when
+  the fixtures change unless the matrix's `adapter-contract` digest is
+  updated too, and this changelog mentions the new digest under
+  `[Unreleased]` (or, just after a release, in its dated section).
 - `skilldeck catalog` (#77): a deterministic, schema-versioned JSON catalog
   of the bundled skills for tools (`--json`), with each skill's name,
   version, category, description, supported agents, canonical content digest

CLAUDE.md

@@ -76,7 +76,11 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   `tests/test_eval_fixtures.py`, and unit-tests the scorer
   (`tests/test_eval_scoring.py`). See `evals/README.md`. New/changed skills
   should be run through them.
-- `docs/` — `authoring-skills.md`, `adapters.md`, `catalog.md`, `releasing.md`
+- `docs/` — `authoring-skills.md`, `adapters.md`, `catalog.md`, `compatibility.md`
+  (the public agent compatibility matrix), `releasing.md`
+- `tests/fixtures/adapter-contracts/` — each adapter's exact rendered file,
+  paths and env-override behaviour for one synthetic skill; checked byte for
+  byte by `tests/test_adapter_contracts.py`
 - `.claude-plugin/marketplace.json` + `claude-plugin/` — the Claude Code plugin
   marketplace tree, **generated** by `scripts/build_plugin.py` from the
   canonical skills; regenerate after changing skills or the project version (a
@@ -102,6 +106,14 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   output.
 - A skill's `meta.yaml` `name` must match its directory name; all metadata fields
   are required and validated by the registry.
+- Any change to an adapter's output format, paths or env handling must update
+  its contract fixtures, the `adapter-contract` digest and matrix rows in
+  `docs/compatibility.md`, and CHANGELOG. The contract tests enforce the
+  fixtures, the digest line, a digest mention in CHANGELOG, and the matrix's
+  path/"Moved by"/scope-error text. Status, minimum versions, dates and notes
+  are maintained by hand (see `docs/compatibility.md#contract-tests`). Only
+  state vendor behaviour a primary source confirms; mark the rest
+  *unverified*.
 - New skills follow the structural template (enforced by
   `tests/test_skill_structure.py`), ground their checklists in **fetched**
   authoritative sources (OWASP/CIS/vendor docs) cited in the skill body, and

README.md

@@ -28,7 +28,9 @@ Every agent gets the same [Agent Skills](https://agentskills.io/specification)
 versions too old for skills, the earlier formats remain available as the
 `copilot-prompt`, `cursor-rule` and `kiro-steering` adapters. See
 [docs/adapters.md](docs/adapters.md) for each agent's locations and minimum
-version.
+version, and the [compatibility matrix](docs/compatibility.md) for how each
+adapter is invoked, which agent versions it was checked against, and how
+well.
 
 ## Claude Code: install as a plugin (no Python needed)
 

docs/adapters.md

@@ -11,6 +11,8 @@ adapter** (`ADAPTERS`, named after the agent) writes that format into the
 agent's own skills folder, and all five render byte-identical files; only the
 folders differ. The formats skilldeck used before remain available as opt-in
 [legacy adapters](#legacy-adapters) for agent versions that predate skills.
+The [compatibility matrix](compatibility.md) sums up each adapter's status,
+how it's invoked, and the agent versions it was checked against.
 
 ## Install locations
 
@@ -114,10 +116,12 @@ So one skill can be found more than once:
 - **Cursor** always reads `.agents/skills`, and also `.claude/skills` when
   third-party extensibility is on. It keeps the first copy per name, in the
   order `.cursor`, `.claude`, `.codex`, `.grok`, `.agents`.
-- **Codex** keeps every copy it finds, and a plain `$name` mention only
-  resolves when exactly one enabled skill has that name. Installing a skill
+- **Codex** keeps every copy it finds. A plain `$name` mention may then not
+  resolve: one of Codex's two skill-selection paths accepts it only when
+  exactly one enabled skill has that name, and the other takes the first
+  match. Which Codex surfaces use which path is unverified. Installing a skill
   for Codex at both project and global scope (or next to a copy of your own
-  in `.codex/skills` or `~/.codex/skills`) breaks `$name` for it.
+  in `.codex/skills` or `~/.codex/skills`) can break `$name` for it.
 - **An old format next to a skill** is not merged at all: VS Code lists a
   Copilot prompt file and a skill of the same name as two `/name` commands,
   and Cursor loads both the rule and the skill.
@@ -329,6 +333,8 @@ land wherever it points.
    should move installs out of it.
 3. Add the agent name to the `supported-agents` list of any skill it should
    apply to.
+4. Add the adapter's contract to `tests/fixtures/adapter-contracts/` and its
+   row to the [compatibility matrix](compatibility.md#contract-tests).
 
 The base class handles `install`/`uninstall` (including the stamp checks,
 symlink handling and atomic writes described above), directory creation, and