Refine agent-compatibility naming and docs

ericzakariasson · ericzakariasson · commit f006be721cf8 · 2026-03-25T14:22:16.000+01:00
Make the plugin read cleanly in public by clarifying score labels, tightening marketplace copy, and aligning the skill and agent names with the review flow.

Made-with: Cursor
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
@@ -36,7 +36,7 @@
     {
       "name": "agent-compatibility",
       "source": "agent-compatibility",
-      "description": "Compatibility scans and agent-native workflow audits for repository setup, startup paths, and validation loops."
+      "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality."
     }
   ]
 }
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc
 | `continual-learning` | [Continual Learning](continual-learning/) | Cursor | Developer Tools | Incremental transcript-driven memory updates for AGENTS.md using high-signal bullet points only. |
 | `cursor-team-kit` | [Cursor Team Kit](cursor-team-kit/) | Cursor | Developer Tools | Internal team workflows used by Cursor developers for CI, code review, and shipping. |
 | `create-plugin` | [Create Plugin](create-plugin/) | Cursor | Developer Tools | Scaffold and validate new Cursor plugins. |
-| `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | Compatibility scans and agent-native workflow audits for repository setup, startup paths, and validation loops. |
+| `agent-compatibility` | [Agent Compatibility](agent-compatibility/) | Cursor | Developer Tools | CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality. |
 
 Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest).
 
diff --git a/agent-compatibility/.cursor-plugin/plugin.json b/agent-compatibility/.cursor-plugin/plugin.json
@@ -2,12 +2,12 @@
   "name": "agent-compatibility",
   "displayName": "Agent Compatibility",
   "version": "1.0.0",
-  "description": "Compatibility scans and agent-native repo audits built around the agent-compatibility CLI. Provides agents and skills that run the published scanner plus workflow-focused reviews for startup paths, validation loops, and documentation.",
+  "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality.",
   "author": {
     "name": "Cursor",
     "email": "plugins@cursor.com"
   },
-  "homepage": "https://github.com/cursor/plugins",
+  "homepage": "https://github.com/cursor/plugins/tree/main/agent-compatibility",
   "repository": "https://github.com/cursor/plugins",
   "license": "MIT",
   "logo": "assets/avatar.png",
diff --git a/agent-compatibility/CHANGELOG.md b/agent-compatibility/CHANGELOG.md
@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this plugin will be documented here.
+
+## Unreleased
+
+- Renamed the full-pass skill to `check-agent-compatibility`.
+- Renamed `deterministic-scan-review` to `compatibility-scan-review`.
+- Renamed `docs-reality-review` to `docs-reliability-review`.
+- Clarified the score model so `Agent Compatibility Score` is the final blended score and `Deterministic Compatibility Score` is the raw CLI score.
+- Tightened the README, marketplace copy, and agent wording for public release.
diff --git a/agent-compatibility/README.md b/agent-compatibility/README.md
@@ -1,70 +1,87 @@
-# Agent Compatibility Cursor Plugin
+# Agent Compatibility
 
-This is a thin Cursor plugin that wraps the published `agent-compatibility` CLI.
+Cursor plugin for checking how well a repo holds up under agent workflows. It pairs the published `agent-compatibility` CLI with focused reviews for startup, validation, and docs reliability.
 
-The top-level skill is intentionally thin. It coordinates one subagent per check and then synthesizes the results.
+By default, the full pass returns one overall score and one short list of the highest-leverage fixes. If the user wants the full breakdown, the agents can expose the component scores and the reasoning behind them.
 
-All review agents are expected to return the same basic shape in **plain text** (no markdown code fences or heading syntax):
+## What it includes
 
-- First line: `<Score Name>: <score>/100`
-- Short summary paragraph
-- Line `Problems` then one issue per line prefixed with `- `
+- `check-agent-compatibility`: full compatibility pass
+- `compatibility-scan-review`: raw CLI-backed scan
+- `startup-review`: cold-start and bootstrap review
+- `validation-review`: small-change verification review
+- `docs-reliability-review`: docs reliability review
 
-The orchestration skill (`run-agent-compatabilty`) answers the user with a minimal markdown result: one `## Agent Compatibility Score: N/100` heading and one flat `Problems / suggestions` list, with no formula or component scores unless the user asks for a breakdown.
+## Score model
 
-## What is in here
+- `Agent Compatibility Score`: final blended score shown to the user
+- `Deterministic Compatibility Score`: raw score from the published CLI
+- `Startup Compatibility Score`: how much guesswork it takes to boot the repo
+- `Validation Loop Score`: how practical it is to verify a small change
+- `Docs Reliability Score`: how closely the docs match the real setup path
 
-- `.cursor-plugin/plugin.json`: plugin manifest
-- `skills/run-agent-compatabilty/SKILL.md`: thin orchestration skill for the full pass
-- `agents/deterministic-scan-review.md`: deterministic CLI scan agent
-- `agents/startup-review.md`: startup verification agent
-- `agents/validation-review.md`: validation-loop agent
-- `agents/docs-reality-review.md`: docs-vs-reality agent
+The final score blends the deterministic scan with the workflow checks:
 
-## How it works
+```text
+Agent Compatibility Score = round((deterministic * 0.7) + (workflow * 0.3))
+```
+
+The CLI also reports an accelerator layer for committed agent tooling. That extra context informs recommendations, but it does not inflate the deterministic compatibility score itself.
+
+## How to use it
+
+Use `check-agent-compatibility` when you want the full pass. That skill fans out to the four review agents above, then returns a compact result:
+
+```md
+## Agent Compatibility Score: 72/100
+
+Top fixes
+- First issue
+- Second issue
+```
+
+Ask for a breakdown if you want the component scores or the weighting.
+
+## CLI notes
+
+The plugin does not bundle the scanner. It runs the published npm package when needed.
+
+Default scan (compact terminal dashboard):
+
+```bash
+npx -y agent-compatibility@latest .
+```
 
-The plugin does not embed the scanner. It expects Cursor to run the published npm package when needed:
+JSON output:
 
 ```bash
 npx -y agent-compatibility@latest --json .
 ```
 
-Or, when a Markdown report is easier to reason about:
+Markdown output:
 
 ```bash
 npx -y agent-compatibility@latest --md .
 ```
 
-## Local install
-
-If you want to use this plugin directly, symlink this plugin directory into:
+Plain text output:
 
 ```bash
-~/.cursor/plugins/local/agent-compatibility
+npx -y agent-compatibility@latest --text .
 ```
 
-## Recommended usage
-
-Use `run-agent-compatabilty` when you want the full pass. That skill should fan out to:
+Config override for ignored paths or weight overrides:
 
-- `deterministic-scan-review`
-- `startup-review`
-- `validation-review`
-- `docs-reality-review`
+```bash
+npx -y agent-compatibility@latest . --config ./agent-compatibility.config.json
+```
 
-The score names should be:
+The scanner is heuristic. It scores repo signals and surfaces likely friction, but it is not a full quality verdict on the codebase.
 
-- `Agent Compatibility Score`
-- `Startup Compatibility Score`
-- `Validation Loop Score`
-- `Docs Reality Score`
+## Local install
 
-## Notes
+If you want to use this plugin directly, symlink this directory into:
 
-- The top-level synthesis combines both layers:
-  - it computes an internal workflow score from startup, validation, and docs-reality
-  - `Agent Compatibility Score` = `round((deterministic * 0.7) + (workflow * 0.3))`
-- The default final user-facing output is intentionally simple: one `Agent Compatibility Score` heading and one flat prioritized `Problems / suggestions` list, with no calculation shown.
-- The skill is intentionally thin. The agents do the work.
-- The CLI remains the scoring engine.
-- If you later want tighter integration, the next step is an MCP server that exposes the scanner as structured tools instead of shell commands.
+```bash
+~/.cursor/plugins/local/agent-compatibility
+```
diff --git a/agent-compatibility/agents/compatibility-scan-review.md b/agent-compatibility/agents/compatibility-scan-review.md
@@ -1,17 +1,17 @@
 ---
-name: deterministic-scan-review
-description: Run the agent-compatibility CLI and return the deterministic score with its main problems
+name: compatibility-scan-review
+description: Run the agent-compatibility CLI and return the raw repository score with its main problems
 model: fast
 readonly: true
 ---
 
-# Deterministic scan review
+# Compatibility scan review
 
-CLI-backed compatibility scan specialist.
+Runs the published scanner and reports the raw repository score.
 
 ## Trigger
 
-Use when the task is specifically to run the published `agent-compatibility` scanner and report the deterministic result.
+Use when the task is specifically to run the published `agent-compatibility` scanner and report the raw compatibility result.
 
 ## Workflow
 
@@ -20,19 +20,20 @@ Use when the task is specifically to run the published `agent-compatibility` sca
 3. Only say the scanner is unavailable after you have actually tried the published package, and the local fallback when it is clearly available.
 4. Prefer JSON when you need structured reasoning. Prefer Markdown when the user wants a direct report.
 5. Keep the scanner's real score, summary direction, and problem ordering.
-6. Do not bundle in startup, validation, or docs-reality judgments. Those belong to separate agents.
+6. Do not bundle in startup, validation, or docs-reliability judgments. Those belong to separate agents.
 
 ## Output
 
 Reply in **plain text only** (no markdown fences, no `#` headings, no emphasis syntax). Use this layout:
 
-First line: `Agent Compatibility Score: <score>/100`
+First line: `Deterministic Compatibility Score: <score>/100`
 
 Then a short summary paragraph.
 
 Then the line `Problems` followed by one bullet per line using `- `.
 
-- Use the deterministic scan's real score.
+- Use the compatibility scan's real score.
+- Keep accelerator context separate from the deterministic compatibility score itself.
 - Include both rubric issues and accelerator issues when they matter.
 - If there are no meaningful problems, under Problems write `- None.`
 - Do not treat scanner availability as a defect in the target repo.
diff --git a/agent-compatibility/agents/docs-reliability-review.md b/agent-compatibility/agents/docs-reliability-review.md
@@ -1,21 +1,21 @@
 ---
-name: docs-reality-review
-description: Check whether the documented setup and run paths survive contact with reality
+name: docs-reliability-review
+description: Check whether the documented setup and run paths reliably lead to the real working path
 model: fast
 readonly: true
 ---
 
-# Docs reality review
+# Docs reliability review
 
-Docs-versus-reality specialist for setup, bootstrap, and run guidance.
+Follows the written setup path and reports where the docs drift from reality.
 
 ## Trigger
 
 Use when the user wants to know whether the repo documentation is actually trustworthy for an agent starting fresh.
 
 ## Workflow
 
-1. Run the deterministic compatibility scan first.
+1. If a compatibility scan result is already available from the parent task, use it as context. Otherwise run the compatibility scan once.
 2. Read the obvious documentation surfaces: `README`, setup docs, env docs, and contribution or agent guidance.
 3. Follow the documented setup and run path as literally as practical.
 4. Note where docs are accurate, stale, incomplete, or misleading.
@@ -31,7 +31,7 @@ Use when the user wants to know whether the repo documentation is actually trust
 
 Reply in **plain text only** (no markdown fences, no `#` headings, no emphasis syntax). Use this layout:
 
-First line: `Docs Reality Score: <score>/100`
+First line: `Docs Reliability Score: <score>/100`
 
 Then a short summary paragraph.
 
diff --git a/agent-compatibility/agents/startup-review.md b/agent-compatibility/agents/startup-review.md
@@ -7,15 +7,15 @@ readonly: true
 
 # Startup review
 
-Startup-path specialist for repository bootstrap and first-run success.
+Tries the cold-start path and reports how much work it takes to get the repo running.
 
 ## Trigger
 
 Use when the user wants to know whether a repo is actually easy to start, not just whether it claims to be.
 
 ## Workflow
 
-1. Run the deterministic compatibility scan first.
+1. If a compatibility scan result is already available from the parent task, use it as context. Otherwise run the compatibility scan once.
 2. Read the obvious startup surfaces: `README`, scripts, toolchain files, env examples, and workflow docs.
 3. Pick the most likely bootstrap path and startup command.
 4. Try to reach first success inside a fixed time budget.
diff --git a/agent-compatibility/agents/validation-review.md b/agent-compatibility/agents/validation-review.md
@@ -7,15 +7,15 @@ readonly: true
 
 # Validation review
 
-Validation-path specialist for self-check loops and targeted verification.
+Checks whether an agent can verify a small change without falling back to a full-repo loop.
 
 ## Trigger
 
 Use when the user wants to know whether an agent can safely verify its own work in a repo.
 
 ## Workflow
 
-1. Run the deterministic compatibility scan first.
+1. If a compatibility scan result is already available from the parent task, use it as context. Otherwise run the compatibility scan once.
 2. Inspect the repo's declared test, lint, check, and typecheck paths.
 3. Decide whether there is a practical scoped loop for a small change.
 4. Try the most relevant validation path.
diff --git a/agent-compatibility/skills/check-agent-compatibility/SKILL.md b/agent-compatibility/skills/check-agent-compatibility/SKILL.md
@@ -1,25 +1,25 @@
 ---
-name: run-agent-compatabilty
-description: Coordinate the full compatibility pass by launching one subagent per check. Use when the user wants the full agent compatibility review instead of only startup, validation, or another single workflow check.
+name: check-agent-compatibility
+description: Run the full repository compatibility pass: scanner score, startup path, validation loop, and docs reliability.
 ---
 
-# Run agent compatabilty
+# Check agent compatibility
 
 ## Trigger
 
-Use when the user wants the full agent compatibility pass for a repo.
+Use when the user wants the full compatibility pass for a repo.
 
 ## Workflow
 
-1. Launch `deterministic-scan-review` to run the CLI and capture the deterministic score and problems.
+1. Launch `compatibility-scan-review` to run the CLI and capture the raw repository score and main issues.
 2. Launch `startup-review` to verify whether the repo can actually be booted by an agent.
-3. Launch `validation-review` to check whether an agent can verify a small change with a credible loop.
-4. Launch `docs-reality-review` to see whether the documented setup and run paths match reality.
+3. Launch `validation-review` to check whether an agent can verify a small change without an unnecessarily heavy loop.
+4. Launch `docs-reliability-review` to see whether the documented setup and run paths reliably match reality.
 5. Use one subagent per task. Do not collapse these checks into one agent prompt.
 6. Compute an internal workflow score as the rounded average of:
    - `Startup Compatibility Score`
    - `Validation Loop Score`
-   - `Docs Reality Score`
+   - `Docs Reliability Score`
 7. Compute an `Agent Compatibility Score` as:
    - `round((deterministic_score * 0.7) + (workflow_score * 0.3))`
 8. Synthesize the results into one final response.
@@ -30,17 +30,17 @@ When scoring internally, use specific non-round workflow scores for the behavior
 
 Respond in markdown, but keep it minimal. Do not use fenced code blocks.
 
-Show **only** one score, as a level-two heading: `## Agent Compatibility Score: N/100`. Do not show how it was computed—no weights (e.g. 70/30), no formula, no deterministic score, no workflow score, no per-check scores, and no arithmetic—unless the user explicitly asks for a breakdown.
+Show only one score, as a level-two heading: `## Agent Compatibility Score: N/100`. Do not show how it was computed, including weights, formula, deterministic score, workflow score, per-check scores, or arithmetic, unless the user explicitly asks for a breakdown.
 
-Then a flat, prioritized list labeled `Problems / suggestions` with one issue per line, each line starting with `- `.
+Then a flat, prioritized list labeled `Top fixes` with one issue per line, each line starting with `- `.
 
-If the deterministic scanner cannot be run because of tool environment issues, say that separately and do not treat it as a repo defect or penalize the repo. Fold deterministic and behavioral findings into that one list instead of separate sections. Focus on highest-leverage fixes. Do not include a separate summary unless the user asks for more detail.
+If the deterministic scanner cannot be run because of tool environment issues, say that separately and do not treat it as a repo defect or penalize the repo. Fold deterministic and behavioral findings into that one list instead of separate sections. Focus on the fixes that would most improve real agent workflows. Do not include a separate summary unless the user asks for more detail.
 
 Example shape:
 
 ## Agent Compatibility Score: 72/100
 
-Problems / suggestions
+Top fixes
 - First issue
 - Second issue
 - Third issue

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@`
`36`	`36`	`{`
`37`	`37`	`"name": "agent-compatibility",`
`38`	`38`	`"source": "agent-compatibility",`
`39`		`- "description": "Compatibility scans and agent-native workflow audits for repository setup, startup paths, and validation loops."`
	`39`	`+ "description": "CLI-backed repo compatibility scans plus Cursor agents that audit startup, validation, and docs against reality."`
`40`	`40`	`}`
`41`	`41`	`]`
`42`	`42`	`}`