feat(skill-management): add migrate-config-to-opus-5 skill - #562
Conversation
Adds a skill that audits and migrates a Claude Code configuration (CLAUDE.md, rules, skills, commands, agents, settings.json, hooks, statusline, CI scripts) for Claude Opus 5's behavioral changes. The skill interviews for scope first (global ~/.claude vs the current project), inventories the surface, classifies findings as mechanical fixes / rewrites / user decisions / deliberate keeps, executes with granular commits, and verifies with a fresh `claude -p` probe. Bundles references/audit-patterns.md covering the four Opus 5 behavioral deltas (verification, delegation, literal instruction-following, output length) plus mechanical checks (stale model IDs, pricing ratios, API params). Bumps skill-management to 1.1.0 (minor: new skill, backward compatible). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📚 Documentation Check ✅Verdict: Passed The plugin version was correctly bumped (1.0.2 → 1.1.0) as a minor bump for the new migrate-config-to-opus-5 skill, matching semver rules for "new skill added." The bump is reflected consistently in both plugin.json and the root CLAUDE.md version table. Plugin-level CLAUDE.md and README.md were both updated to describe the new skill, and the new skill files (SKILL.md, references/audit-patterns.md) were added to the plugin.json skills array correctly (not commands). Naming convention (verb-noun: "migrate-config-to-opus-5") is satisfied. Documentation Review — PR #562Plugin version bump (CRITICAL check): PASS
Plugin CLAUDE.md: PASS
Plugin README.md: PASS
Naming convention: PASS
Changelog: N/A
Root CLAUDE.md plugin-count snapshot: Unaffected — no plugins were added/removed (only a skill within an existing plugin), so the "8 plugins" snapshot line and No missing documentation updates found. This PR fully satisfies the mandatory version-bump and documentation-sync rules in ✨ No Documentation Updates NeededAll documentation appears to be up to date with the code changes. 🤖 Generated by Claude Documentation Validator | Mode: |
|
● Reviewed · against Latest: ✅ approved ← prior: ✅ approved ← 🚨 changes requested (4) Note Approved — one doc-parity nit on the delivery rule, tracked in an open thread. Adds a AssessmentThe publishing contract checks out: manifest matches disk in both directions, the minor bump ships in the same commit, and all three doc surfaces agree. Every mechanical-fix claim in Suggestions
Iteration history · 3 reviews2026-08-04 22:28 UTC · ✅ approved · 0 findings ·
|
- Widen plugin-level descriptions (plugin.json, README, CLAUDE.md) to cover full-config migration, so the new skill is discoverable from the plugin listing - Date-stamp the model-ID and pricing facts in audit-patterns.md so future staleness is visible Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2670e105e8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Keep (policy):** cost-routing tables (cheap models for mechanical steps — that's economics), and adversarial-review/verification dispatches the user explicitly wants in fresh contexts. If the user has such a policy, write the cap language _with an explicit carve-out_ naming it, or the cap will silently eat the gate. | ||
|
|
||
| **Related stale fact:** pre-2026 configs often justify model routing with "Opus costs ~5x Sonnet". Claude 5 pricing: Opus 5 $5/$25 per MTok vs Sonnet 5 $3/$15 → ~1.7x. Haiku ($1/$5) is still ~5x under Opus. Update any cost-ratio claims and thresholds derived from them. |
There was a problem hiding this comment.
As of August 4, 2026, this mechanical pricing fix hard-codes the post-September 1 Sonnet 5 price. Anthropic's current pricing page lists Sonnet 5 introductory pricing through August 31, 2026 at $2/$10 per MTok while Opus 5 is $5/$25, so the current Opus/Sonnet ratio is 2.5x, not ~1.7x. If someone runs this migration before September 1, the skill can rewrite cost-routing claims and thresholds to the wrong ratio; date-qualify this guidance or include both current and future prices. Source: Anthropic pricing.
Useful? React with 👍 / 👎.
|
|
||
| ## Settings that need a user decision | ||
|
|
||
| - **effortLevel** (Claude Code setting): Opus 5's default is xhigh; low/medium are unusually strong on this model, so a pinned `high` from the 4.x era is worth revisiting. Never change this one mechanically — present the trade (cost/latency vs depth) in the Step 3 interview and let the user pick; log a checkpoint to revisit after a week of use. |
There was a problem hiding this comment.
This tells the migration skill that Opus 5 defaults to xhigh, but Anthropic's migration guide says the Opus 5 default is high on both the Claude API and Claude Code. That false baseline will mislead the required user-decision interview for effortLevel and can make an existing pinned high look like a downshift from the default when it is actually the default; keep the useful "re-run an effort sweep" advice without claiming xhigh is the default. Source: Anthropic migration guide.
Useful? React with 👍 / 👎.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| ## Mechanical checks (no judgment, just fix) | ||
|
|
||
| - **Model IDs:** `/usr/bin/grep -rE 'claude-(opus|sonnet|haiku)-[0-9]' <scope>` across scripts, CI, statuslines, agent frontmatter, scheduled-task registrations. Current IDs (as of 2026-08): `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`. Aliases (`opus`, `sonnet`, `haiku`) are self-updating — prefer them where a pin isn't required. |
There was a problem hiding this comment.
claude-(opus|sonnet|haiku)-[0-9] never matches Claude 3.x IDs, which put the tier after the version (claude-3-opus-20240229, claude-3-5-sonnet-20241022). Those are exactly the retired, now-404 pins most likely to be in a pre-Opus-5 config, and this "mechanical, no judgment" check reports clean on them.
| - **Model IDs:** `/usr/bin/grep -rE 'claude-(opus|sonnet|haiku)-[0-9]' <scope>` across scripts, CI, statuslines, agent frontmatter, scheduled-task registrations. Current IDs (as of 2026-08): `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`. Aliases (`opus`, `sonnet`, `haiku`) are self-updating — prefer them where a pin isn't required. | |
| - **Model IDs:** `/usr/bin/grep -rE 'claude-(opus|sonnet|haiku|fable|mythos)-[0-9]|claude-[0-9]' <scope>` across scripts, CI, statuslines, agent frontmatter, scheduled-task registrations. The second alternative catches the Claude 3.x scheme (`claude-3-opus-…`, `claude-3-5-sonnet-…`), where the tier follows the version. Current IDs (as of 2026-08): `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5` (plus `claude-fable-5` where the top tier is wanted). Aliases (`opus`, `sonnet`, `haiku`) are self-updating — prefer them where a pin isn't required. |
| - **Model IDs:** `/usr/bin/grep -rE 'claude-(opus|sonnet|haiku)-[0-9]' <scope>` across scripts, CI, statuslines, agent frontmatter, scheduled-task registrations. Current IDs (as of 2026-08): `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`. Aliases (`opus`, `sonnet`, `haiku`) are self-updating — prefer them where a pin isn't required. | ||
| - **Context-window logic:** scripts branching on model ID for window size. All current non-Haiku models are 1M; Haiku 4.5 is 200K. Keying "haiku → 200K, else 1M" beats enumerating model names. Test with synthetic payloads for both branches. | ||
| - **API params:** `budget_tokens` is rejected with a 400 on the Claude 5 family — replace `thinking: {type: "enabled", budget_tokens: N}` with `thinking: {type: "adaptive"}`. Also flag hardcoded `temperature` alongside thinking, and Priority Tier assumptions (not supported on Opus 5). | ||
| - **Dead weight:** vendored commands referencing nonexistent agents, archive directories, `.backup`/`.bak` settings snapshots (these often pin old models), marketplace entries pointing at dead repos. Delete; git holds history. |
There was a problem hiding this comment.
skill-doctor/SKILL.md:43 documents ~/.claude as the user's non-git config, and SKILL.md:51 itself hedges "if the surface is a git repo". With dead entries classified as "fix mechanically — no interview needed" (SKILL.md:40), deleting .backup/.bak snapshots there is unapproved and unrecoverable.
| - **Dead weight:** vendored commands referencing nonexistent agents, archive directories, `.backup`/`.bak` settings snapshots (these often pin old models), marketplace entries pointing at dead repos. Delete; git holds history. | |
| - **Dead weight:** vendored commands referencing nonexistent agents, archive directories, `.backup`/`.bak` settings snapshots (these often pin old models), marketplace entries pointing at dead repos. Delete only when the surface is a git repo with a clean tree — git holds history there. On a non-git surface (a plain `~/.claude`), list them for the Step 3 interview instead of deleting. |
| - One granular commit per logical change (if the surface is a git repo). Never one big migration commit — the user needs to be able to revert a single decision. | ||
| - For shared/synced files, apply the machine-agnostic path rule from Step 0. | ||
| - When editing `settings.json`, validate with `python3 -c "import json; json.load(open('...'))"` after every edit, and check `git diff` first so pre-existing drift from other sessions is named in the commit message rather than silently swept in. | ||
| - Delete dead things outright (superseded commands, archives, backup files) — git history is the recovery path; "kept for recovery" copies keep loading into context. |
There was a problem hiding this comment.
|
|
||
| If the user picked global and `~/.claude` is a git repo shared across machines, every path fix must be machine-agnostic (`$HOME`, `~/`, resolver scripts) — a literal home-dir path that is correct on this machine is silently wrong on the others. | ||
|
|
||
| In the same interview, ask one execution question: apply edits directly with granular commits (the default), or propose the full diff for review first. |
There was a problem hiding this comment.
🔵 info · consistency — Defaulting to "apply edits directly with granular commits" inverts the sibling skill's delivery rule (skill-doctor/SKILL.md:47: repo files ship as a draft PR, never an in-place edit on the working branch). On project scope this commits straight to whatever branch is checked out.
There was a problem hiding this comment.
Caution
- Widen the model-ID grep to also match Claude 3.x-era IDs (claude-3-opus-..., claude-3-5-sonnet-...) where the version precedes the tier - Note Sonnet 5 introductory pricing ($2/$10 through 2026-08-31, ratio ~2.5x) so the mechanical pricing fix isn't wrong pre-September - Condition dead-weight deletion on a git surface; on non-git configs require a confirmed backup or a user decision - Align project-scope delivery with skill-doctor: edits land on a branch + PR, not the checked-out branch - Disambiguate effortLevel: Claude Code defaults Opus 5 to xhigh, the raw API default is high Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Note
✅ Approved — see full review in the sticky comment ↑
Tightens the project-scope delivery rule to match skill-doctor exactly: the PR branch comes off origin/<default>, not whatever is checked out. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…stions for migrate-config-to-opus-5 (#564) * fix(skill-management): apply residual review suggestions to migrate-config-to-opus-5 Applies the two github-actions[bot] inline suggestions from PR #562 that were not fully adopted before merge: - Model-ID grep now also matches fable/mythos tier IDs, and the current-IDs list mentions claude-fable-5 for top-tier use - Dead-weight deletion now requires a clean tree on git surfaces, and routes non-git dead weight to the Step 3 interview Patch bump skill-management 1.1.0 -> 1.1.1. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skill-management): mirror clean-tree deletion rule in SKILL.md Step 4 Codex review flagged that the executable workflow text still permitted outright deletion on any git repo while the reference required a clean tree. Both now agree: clean tree required, dirty/non-git dead weight routes to the Step 3 interview. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(skill-management): subagent read-every-file audit in migrate-config-to-opus-5 Step 2 now mandates a subagent fan-out that reads each in-scope file in full, audits it against references/audit-patterns.md, and reports structured per-file findings (quoted text, proposed change, classification, rationale) back to the main thread. Grep sweeps are demoted to a completeness cross-check — a hit in an unreported file means a missed batch, never a patch source. Bump becomes minor (1.1.1 -> 1.2.0) since this is a feature-level enhancement; plugin CLAUDE.md and README updated to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skill-management): include classification buckets in subagent payload AI review caught that the contract referenced 'the four buckets below' while the enumerated payload omitted them — subagents never see the rest of SKILL.md, so each would invent its own labels. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skill-management): forward-looking destination for mid-execution dead weight Step 4 routed dirty-tree/non-git dead weight back to the Step 3 interview, which has already run by then. Now a follow-up AskUserQuestion, with Step 3 as the ideal earlier surfacing point. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 participant
Summary
Ports the
migrate-config-to-opus-5skill into theskill-managementplugin for team-wide use. The skill audits and migrates a Claude Code configuration (CLAUDE.md, rules, skills, commands, agents, settings.json, hooks, statusline, CI scripts) for Claude Opus 5's behavioral changes.What the skill does:
~/.claudevs the current projectreferences/audit-patterns.md— the four Opus 5 behavioral deltas (self-verification, delegation, literal instruction-following, output length) with concrete search patterns and fix shapesclaude -pprobePlugin changes:
packages/plugins/skill-management/skills/migrate-config-to-opus-5/(SKILL.md + references/audit-patterns.md)plugin.json: skill registered, version bumped 1.0.2 → 1.1.0 (minor: new backward-compatible skill)Why
skill-management: this plugin is the curation layer over the Claude Code customization surface (inventory, audit, improve). A model-migration audit of that same surface fits its charter;claude-setupis about bootstrapping new repos, not migrating existing config.Test plan
node scripts/validate-plugin.cjs packages/plugins/skill-managementpassesbunx markdownlint-cli2clean on all touched filesbunx nx format:write --uncommittedapplied🤖 Generated with Claude Code