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:

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."
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?

Compatibility scan — for projects running both Opus 4.6 and 4.7. Holds back 4.7-only optimizations that would degrade 4.6.
4.7-only scan — for projects fully migrated off 4.6. Surfaces every finding with no holdback.
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

Dis

opus-compatibility-scanner