Opus Compatibility Scanner

Opus 4.6 ⇄ 4.7 Compatibility Scanner

Scans a Claude Code project for two classes of issues that need fixing when migrating from Claude Opus 4.6 to Claude Opus 4.7:

1. Prose-pattern issues in CLAUDE.md, AGENTS.md, subagent definitions, and skill bodies — directives 4.6 silently inferred a sensible interpretation for, but 4.7 will read literally. Anthropic's own migration guide flags this as the headline behavioral change: "Claude Opus 4.7 interprets prompts more literally and explicitly than Claude Opus 4.6 ... It will not silently generalize an instruction from one item to another, and it will not infer requests you didn't make."
2. Configuration / API artifact issues in .claude/settings.json, hook scripts, package manifests, and any source code that calls the Anthropic SDK — model IDs, deprecated thinking modes, removed parameters, beta headers, SDK version floors, etc.

This skill is recommend-only by default. It produces a report; it never modifies files without an explicit per-fix confirmation in conversation.

Announce at start: "I'm using the opus-compatibility-scanner skill to scan your project for Opus 4.6 / 4.7 compatibility issues."

Core principle: Never modify a file the user hasn't explicitly approved. The scan is a diagnostic; the user decides what to apply, one fix at a time.

When to Load References

This skill has substantial domain knowledge split into references/. Load each file only when needed:

• references/patterns-prose.md — Load during Phase 2 when matching patterns against CLAUDE.md, AGENTS.md, subagent definitions, or skill SKILL.md files. The pattern count is enumerated dynamically at scan time.
• references/patterns-config.md — Load during Phase 2 when matching against .claude/settings.json, hook scripts, package manifests, or Anthropic SDK call sites. The pattern count is enumerated dynamically at scan time.
• references/sources.md — Load when rendering a finding and need to cite a source with its tier (1-4). Every finding must include a citation.
• references/report-template.md — Load during Phase 4 when rendering the executive-summary report.
• references/contradictions.md — Load during Phase 3 when running pair-detection patterns (G1, G2, R3, M1). Documents the heuristic + LLM-judgment algorithm.
• references/symptoms.md — Load when the user describes a symptom ("my agent is acting weird since 4.7") rather than asking for a general scan. Maps symptoms back to pattern IDs.

When to use

See the trigger list in the YAML description above. Also run proactively whenever the user mentions upgrading from 4.6 to 4.7, when they describe any behavior regression after a model swap, or when you notice them about to flip the model.

How the scan works

The scan is one pass with five steps: a Phase 0 introduction and mode selection, then three read-only phases (discovery, pattern matching, severity classification), then a fourth phase that renders the executive-summary report. The user picks a mode in Phase 0 before any file is read. After the scan, the response presents findings in priority order, and file modifications happen only when the user accepts a specific fix in conversation, one at a time — see "How to respond to the user" below.

Phase 0 — Introduce and select mode

Post the intro and option list to the conversation. Wait for the user's reply. Do not run discovery, pattern matching, or any tool until the user has picked a mode.

Default-mode hint from invocation phrasing. Use the user's invocation language to pre-select an option, but do not skip the prompt:

• Slash command (/opus-compatibility-scanner) or any compatibility-trigger phrase → option 1 is the suggested default.
• Any 4.7-only-trigger phrase ("I'm 4.7-only now", "after upgrading to 4.7", "since switching to 4.7") → option 2 is the suggested default.
• Any symptom phrase ("my agent is acting weird since 4.7", "4.7 broke X", "model swap broke X") → option 3 is the suggested default.

If pre-selection is ambiguous, present the menu without highlighting a default.

The user sees this — render as plain markdown, do NOT wrap in a fenced code block. Do not re-introduce the skill — the announcement line above has already done that. Lead with the value description, then the menu.

I check for instructions Opus 4.7 reads more literally than 4.6, plus config and SDK call sites that may now error or behave differently. I'll surface findings, then walk fixes one at a time so you stay in control of every edit.

What would you like to do?

1. Compatibility scan — for projects running both Opus 4.6 and 4.7. Holds back 4.7-only optimizations that would degrade 4.6.
2. 4.7-only scan — for projects fully migrated off 4.6. Surfaces every finding with no holdback.
3. Diagnose a behavior change — you switched to 4.7 and something broke. I'll scan in compat mode, then surface symptom-mapped findings first.

Reply 1, 2, or 3.

Routing rules after the user replies:

• Option 1 → compat mode for Phase 3 (suppression + apply-tier downgrades active).
• Option 2 → 4.7-only mode for Phase 3 (no suppression, no downgrade).
• Option 3 → compat mode + symptom relevance ranking. Ask one short follow-up first: "Briefly, what's the behavior change?" Use the reply to look up symptom-to-pattern mappings in references/symptoms.md. After Phase 4, the executive summary prepends a "Most relevant to your symptom" subsection listing the matching findings before the standard severity rollup. If no symptom-mapped finding hits, fall through to the standard executive summary plus an offer to walk references/symptoms.md interactively.

If the user replies with anything other than 1, 2, 3, or a synonym, ask once more for clarity rather than guessing.

Phase 1 — Discovery

Enumerate every file in scope. Use Glob and Bash from the project root.

Prose files (Class A — patterns-prose.md applies):

# Project-level CLAUDE.md (any depth)
find . -type f \( -iname "CLAUDE.md" -o -iname ".claude.md" -o -iname ".claude.local.md" -o -iname "AGENTS.md" \) ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*opus-compatibility-scanner*" 2>/dev/null

# Subagent + skill definitions
find .claude/agents -type f -name "*.md" ! -path "*opus-compatibility-scanner*" 2>/dev/null
find .claude/skills -type f -name "SKILL.md" ! -path "*opus-compatibility-scanner*" 2>/dev/null

Also check for the user-global file: ~/.claude/CLAUDE.md. If it exists, scan it too — but flag findings there as [GLOBAL] so the user knows the change affects all their projects.

# User-global memory file (flag findings as [GLOBAL] in the report)
ls -la ~/.claude/CLAUDE.md 2>/dev/null

When scanning ~/.claude/CLAUDE.md, every finding from that file is rendered with [GLOBAL] prefix in the executive summary and drill-down. Editing the global file requires the user to reply with an explicit phrase that names the file (see "Constraints on what gets edited" below), since the change affects every project on the user's machine.

Config / API files (Class B — patterns-config.md applies):

# Settings + hooks
ls -la .claude/settings.json .claude/settings.local.json 2>/dev/null
find .claude/hooks -type f ! -path "*opus-compatibility-scanner*" 2>/dev/null
find .claude -type f -name "*.json" ! -path "*opus-compatibility-scanner*" 2>/dev/null  # MCP, etc.

# Package manifests
ls -la package.json requirements.txt pyproject.toml Pipfile Cargo.toml go.mod 2>/dev/null

# Source files likely to contain API calls or model IDs
grep -rln "anthropic\|claude-opus\|claude-sonnet\|claude-haiku" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.mjs" --include="*.py" --include="*.go" --include="*.rs" --include="*.java" --include="*.cs" --include="*.toml" --include="*.yaml" --include="*.yml" --include="*.json" --include="*.sh" . 2>/dev/null | head -100

Discovery runs silently. The file count surfaces in the executive-summary first line (Scanned files. Found: …).

Phase 2 — Pattern matching

Load the pattern catalogues:

• [references/patterns-prose.md](references/patterns-prose.md) — Class A patterns (count enumerated dynamically at scan time)
• [references/patterns-config.md](references/patterns-config.md) — Class B patterns (count enumerated dynamically at scan time)
• [references/sources.md](references/sources.md) — citation library (Tier 1 = official Anthropic; Tier 3 = practitioner consolidation)
• [lib/regex-engine.md](lib/regex-engine.md) — Grep-tool-only mandate (PCRE2)

Grep tool mandatory. Pattern matching against file contents goes through the Claude Code Grep tool (PCRE2). Bash grep is NEVER used for pattern matching. Bash is reserved for Phase 1 discovery (find, ls, file enumeration). See lib/regex-engine.md for rationale.

Per-pattern dispatch on match.engine:

• pcre2 → Grep tool with the pattern's match.pattern regex. Returns structured {file, line, column, match_text}.
• structural → call the named check function. Currently defined: messages-array-last-element-is-assistant (CB6 — parses the source's messages: [...] array and verifies the LAST element does NOT have role: "assistant"); cross-file-rule-diff (M1 — diffs declared rules across parent/child CLAUDE.md files for same-rule contradictions).

Class B match dispatch additionally consults applies_to_files glob to scope the search before invoking Grep.

JSONC files (.claude/settings.json, .claude/settings.local.json) — when matching Class B patterns inside these files, mentally strip // line comments and /* */ block comments before reasoning about structure. Don't write a parser for it; the patterns themselves are robust to comment whitespace.

Every match produces a finding record per the manifest schema: {file, line, col, pattern_id, matched_substring, severity, tier, apply_tier}.

Phase 3 — Severity classification

Mode is already set (Phase 0). Phase 3 branches on the mode the user picked:

• Option 1 → Compatibility mode.
• Option 2 → 4.7-only mode.
• Option 3 → Compatibility mode plus symptom relevance ranking applied at Phase 4.

In compatibility mode:

1. Filter out every prose finding whose pattern carries **Compatibility:** 🔴 in its catalogue record. Suppressed findings are still counted (see "Suppression dedup" below) for the end-of-scan offer.
2. For every config finding whose pattern carries **Compatibility:** 🔴, downgrade apply_tier from direct to guided. The drill-down prompt for those findings explicitly asks the user to confirm the call site is 4.7-bound before the edit applies.

In 4.7-only mode: no suppression, no apply-tier downgrade. All 🔴 findings surface with their default rewrites and apply tiers.

Suppression dedup. When two or more 🔴 prose patterns match overlapping spans on the same (file, line) pair (matched-substring spans overlap by ≥1 character), collapse to a single suppressed-finding count and a single drill-down record. The drill-down entry on opt-in lists all merged pattern IDs in its header for traceability. The dedup applies to the suppressed set only; non-🔴 dedup behavior is unchanged.

Categorical labels for the end-of-scan offer. When summarizing suppressed findings: | Pattern ID | Category label | |---|---| | F3, F6, F7 | scaffolding deletion(s) | | A4, A5 | verbosity-cap removal(s) | | R6 | ask-clarifying-questions removal(s) |

Group suppressed findings by category, then count and pluralize. Example output: "2 scaffolding deletions, 1 verbosity-cap removal."

1. Apply severity per pattern (as-declared in the pattern schema).
2. Enforce Critical-requires-Tier-1 filter (demote any Critical with Tier > 1 to Warning). Also enforce: if source.fidelity == practitioner, cap severity at Warning regardless of declared severity.
3. Class A semantic-judgment step — for every Class A match where the pattern's match.high_precision is false (the default):

• Read ±5 lines around the matched line. Pass to calling Claude with prompt: "Is this match a directive to Claude (the model executing this CLAUDE.md / agent / skill), or is it descriptive prose / user-copy / website-behavior description / operational guardrail / example block? Reply DIRECTIVE or NOT_DIRECTIVE."
• If NOT_DIRECTIVE, suppress the finding. Manifest annotation: suppressed_by: phase3_semantic_check.
• If DIRECTIVE, retain the finding for severity classification.
• Why both applies_to_files and this step: applies_to_files is the structural filter (path-based, deterministic, fast). The semantic step catches false positives within in-scope files where the regex matched a non-directive sentence (e.g., "users who prefer dark mode" inside a CLAUDE.md describing site behavior; "NEVER write an entire long file (100+ lines)" as an operational write-size guardrail rather than a Claude verbosity cap). Two different failure modes, two different mechanisms.
• Cost control: the semantic check is skipped when match.high_precision: true. Pattern authors opt in to high_precision only when the regex is anchored enough that semantic disambiguation isn't needed (literal API field names, exact directive phrases that only appear in instruction contexts, etc.). Class B patterns ignore the field — the semantic step is Class-A-prose-only.

1. Deduplicate overlapping matches — if one line matches multiple patterns, merge into ONE finding listing all pattern_ids; rewrite is the most conservative applicable.
2. Run pair-detection patterns (G1, G2, R3, M1) via the hybrid heuristic + LLM-judgment algorithm. Full algorithm in references/contradictions.md.
3. All findings (Tier 1, 2, 3) are surfaced; the executive summary groups them by severity, not by tier. Tier is shown alongside the citation so the user can judge weight.

Phase 4 — Report rendering

The first response after the scan is the executive summary, rendered as plain markdown (the intro was already shown in Phase 0; do not repeat it). Concise rewrites are the default per-finding rendering; the expanded rewrite is shown only when the user asks explain during drill-down.

No files are written during the scan. The drift check at fix time works from the live file (re-reading ±3 lines around the matched line, see "Response shape: applying a fix" below), so the manifest is not required for safe edits. After the scan flow completes, the skill offers — but never silently writes — a manifest (.claude/opus-4.7-migration-manifest.json) and/or a human-readable report (.claude/opus-4.7-migration-report.md) for users who want an audit trail or a way to resume in a later session. Both offers default to no. The manifest schema in lib/manifest-schema.json describes the opt-in shape.

How to respond to the user

The intro and option list were already shown in Phase 0 — never repeat them. After the scan completes, the first response IS the executive summary, rendered as plain markdown. Wait for the user's reply before drilling down.

Diagnose mode addendum. When mode is option 3 (Diagnose), the executive summary prepends a "Most relevant to your symptom" subsection listing findings whose pattern IDs map to the symptom the user described. The standard severity rollup follows. If no symptom-mapped finding hits, omit the subsection and offer to walk references/symptoms.md interactively at the end.

Response shape: executive summary (first response)

The user sees this — render as plain markdown, do NOT wrap in a fenced code block. Use the literal severity emoji 🔴 🟡 🔵 inline so each row is scannable. Replace `` placeholders with actual values; omit any row whose count is zero EXCEPT the Critical row, which always renders.

Scanned `` files. Pattern catalog current through 2026-04-26.

• 🔴 Critical: ` — `
• 🟡 **Warning

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: readysolutionsai
• Source: readysolutionsai/opus-compatibility-scanner
• License: MIT
• Homepage: https://readysolutions.ai/blog/2026-04-26-opus-4-7-compatibility-scanner-claude-code/

Install and usage instructions live in the source repository linked above.