agentleFS
puedingpueding/houserules/skills/migrate/SKILL.md

migrate

Skill1 starsChanged 3 months agoMITView on GitHub

Re-fit a CLAUDE.md to the model that will actually read it. Removes what the new model no longer needs, adds what it now requires, and rewrites what changed — driven by Anthropic's live prompting guide for that model. Briefs you on what Anthropic says, then gives you a numbered table of proposed changes to pick from. Use when the user runs /houserules:migrate, or asks to migrate, re-fit, re-calibrate, modernize, or update CLAUDE.md for a new Claude model. Not for auditing CLAUDE.md against the codebase — that is claude-md-improver's job.

65 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use incident, sdd and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JkudjoSkill

    incident

    Production incident response — structured triage, hypothesis tree, safe remediation, incident record

    Also in 4 projects that use this

  • liatrio-labsSkill

    sdd

    Execute the Liatrio Spec-Driven Development (SDD) workflow when explicitly invoked by the user. NOTE: this skill is NOT intended to be dynamically loaded or automatically triggered; it should only ever be explicitly called by the user.

    Also in 4 projects that use this

  • BerryKuipersSkill

    scaffold

    Detect project stack, apply architecture patterns, wire quality gates, and scaffold features. Use when bootstrapping a project, adding a vertical slice, wiring CI/CD, adding Docker compose, or setting up quality gates.

    Also in 4 projects that use this

  • agenticnotetakingSkill

    upgrade

    Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for improvements", "update methodology".

    Also in 3 projects that use this

  • genomewalkerSkill

    checkpoint

    Save a checkpoint of task status, decisions, active files, and next steps

    Also in 5 projects that use this

  • JohnJBorenSkill

    ci-cd

    CI/CD pipeline design, GitHub Actions, testing automation, and deployment strategies

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 51 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Output contract — the user picks, the skill does not decide: Every run produces two things, in this order:

    line 29
  2. Very specific:

    Follow @import lines (e.g.

    line 67
  3. Very specific:

    Read references/model-docs.md for URL patterns, then WebFetch the guides.

    line 97
  4. Distinctive:

    Never delete on keyword match.

    line 172
  5. Distinctive:

    KEEP rows go last, and only include a KEEP row when the user might expect it to be cut — otherwise it is noise.

    line 220
  6. Distinctive:

    Every row cites its evidence: a verbatim quote from the live guide, a quoted line from your own system prompt, a named installed skill, or …

    line 241
  7. Distinctive:

    Do not ask an open-ended "what would you like to do?" — the user picks numbers.

    line 257
  8. Distinctive:

    Only the numbers the user named.

    line 263
  9. Distinctive:

    Write MOVE extractions to their destination before removing from the source.

    line 271
  10. Distinctive:

    If the user picked a subset, say plainly which numbered rows were skipped so the remainder is not silently lost.

    line 282

“Common” is measured: kept by at least 6 in 10 of the 51 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

houserules:migrate

Re-fit CLAUDE.md to the model that will read it. A CLAUDE.md is written against one model's behavior. Point it at a different model and it is mis-fitted in both directions at once:

  • Rules written to patch a weakness the new model does not have are not neutral — they cost tokens, and some fire twice against behavior it now has natively.
  • Behaviors the new model introduced have no rule at all yet. Longer default responses, longer written deliverables, readier delegation: each needs an instruction that was never necessary before.

Migration is not pruning. Anthropic ships a per-model prompting guide with an explicit remove this list and an explicit add this list on every release. A migration that only deletes has done half the job. This skill reads that guide live, shows the user what it says, and re-fits their CLAUDE.md to it — removing, adding, and rewriting as the guide directs.

This skill hardcodes zero model facts. A skill with one model's rules baked in becomes the exact technical debt it exists to delete. Everything model-specific is fetched at runtime.

Output contract — the user picks, the skill does not decide. Every run produces two things, in this order:

  1. A briefing — what Anthropic currently says about this model, quoted, with the source URL. The user should learn something even if they change nothing.
  2. A numbered table of proposed changes — one row per change, pickable by number. Nothing is written until the user names the numbers they want.

Scope boundary

QuestionSkill
Does CLAUDE.md accurately describe the codebase?claude-md-improver
Is CLAUDE.md still calibrated to the model reading it?this skill
Which rules should I have, based on how I actually work?houserules:learn
Both at once, reconciled into one table?houserules:fit
Do my API calls use the right model ID / params?/claude-api migrate

Say so if the user wants one of the other two.


Phase 1 — Resolve targets

InvocationBehavior
/houserules:migrate ~/.claude/CLAUDE.mdAudit that one file
/houserules:migrate ./CLAUDE.mdAudit that one file
/houserules:migrateDiscover every CLAUDE.md, then audit

Discovery (no-arg mode):

ls -1 ~/.claude/CLAUDE.md 2>/dev/null
find . -maxdepth 4 \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name AGENTS.md \) \
  -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null

Follow @import lines (e.g. @RTK.md) — imported files load into context too. Paths are case-insensitive on macOS; claude.md resolves to CLAUDE.md.

Report cost per workspace, not per file. Files do not load individually — a session loads the global file plus that project's files. Rank by what actually loads together, or the biggest single file will look like the biggest problem when it is not:

# global baseline, then per-project stack

Roughly bytes / 3.7 ~= tokens. In no-arg mode, confirm the target set before auditing. If a target does not exist, say so plainly; do not invent one.


Phase 2 — Identify the model

  1. $ANTHROPIC_MODEL if set.
  2. The model running this session, if known.
  3. Otherwise, ask. Do not guess.

A CLAUDE.md tuned for the wrong model is the problem this skill exists to solve — do not reproduce it.


Phase 3 — Fetch the live guidance, and SHOW IT

Read references/model-docs.md for URL patterns, then WebFetch the guides.

Then print a briefing before any audit output. The user asked what Anthropic says — tell them, in Anthropic's words, with the link. This section stands on its own: it should be worth reading even if they apply zero changes.

## What Anthropic says about <model>
Source: <url>   (fetched live this run)

REMOVE from your instructions
  • "<verbatim quote from the guide>"
    -> why: <one line>

ADD to your instructions
  • "<verbatim recommended snippet from the guide>"
    -> why: <one line>

BEHAVIOR CHANGES that affect how you should write instructions
  • <behavior> — <what it means for a CLAUDE.md>

Quote the guide verbatim — do not paraphrase into your own words. The point is that the user sees the primary source. Include the recommended snippets in full; they are short and they are the actual deliverable for the ADD rows.

If the fetch fails, say so in place of the briefing and continue with Phase 4 categories D–F only, which need no model data. Never fabricate guidance, and never present a degraded audit as a complete one.


Phase 4 — Audit

Classify every rule into exactly one category. Worked examples for each are in references/audit-taxonomy.md.

CategoryVerdictTest
AModel-compensationDELETEThe live guide says to remove it
BHarness duplicationDELETEAlready in your own system prompt
CEcosystem duplicationDELETEOwned by an installed skill/plugin/hook
DInternal contradictionREWRITETwo rules that cannot both hold
EUnexecutableDELETEReferences state the model cannot observe
FScope misplacementMOVEGlobal rule that is project-conditional
GGenuine preferenceKEEPDescribes how the user wants to work
HUnmet new behaviorADDThe guide recommends it and the file lacks it

Category H is not optional and not secondary. Work the guide's add this list as deliberately as its remove this list: walk every recommended snippet and check whether the file already covers it. A migration that returns only deletions means H was skipped, not that H was empty.

Verify the file's claims against reality

Category E is not only about spend and wall-clock. A rule that names a thing must be checked against whether that thing exists. Text-only reasoning misses this, and it is where the highest-value findings hide.

ls ~/.claude/agents/ 2>/dev/null              # do named sub-agents exist?
ls ~/.claude/skills ~/.claude/plugins/marketplaces 2>/dev/null

Then check named tools and flags against your own available tool list. A routing table pointing at seven sub-agents that were never created is dead config, and it looks perfectly reasonable as prose.

G. Keep — PROTECT

Read this before proposing a single deletion.

No model release makes a preference obsolete. This is the category the skill is most likely to get wrong, and getting it wrong is destructive.

Never delete on keyword match. Before flagging anything containing "verify", "check", "validate", "ensure":

Looks like a hitActuallyVerdict
"JWT verification, HMAC signatures"Domain vocabularyKEEP
"Run flutter analyze before committing"External gate - real outputKEEP
"Watch the test fail before implementing"TDD mechanic - external gateKEEP
"Have Codex review the plan"Cross-model review, not self-reviewKEEP
"Double-check your answer before responding"Self-verificationDELETE

Self-directed re-checking is scar tissue; an external gate that produces real output is not. A tool invocation is never self-verification.

Style, tone, workflow methodology, team conventions, domain vocabulary: all KEEP. Cutting for its own sake is the failure mode.


Phase 5 — The pickable table

Two tiers. The table is the index the user picks from; the detail below carries the full text so nothing is truncated.

Tier 1 — the table

## Proposed changes — /path/to/CLAUDE.md
188 lines / 8,682 B / ~2,346 tok per session

| #  | Lines   | What                    | Verdict | Why                                  |
| -- | ------- | ----------------------- | ------- | ------------------------------------ |
| 1  | 89-113  | Sub-agent routing table | DELETE  | all 7 agents missing from disk       |
| 2  | 91      | "only works through..." | REWRITE | Agent tool now takes a `model` param |
| 3  | (new)   | Deliverable length      | ADD     | guide recommends it; file lacks it   |
| 4  | 63-66   | Scope Control para 1    | KEEP    | duplicates harness, but 4 lines      |

Projected if all applied: 188 -> 170 lines

Rules for the table:

  • Number every row. The numbers are how the user replies.
  • One row per change. Never bundle two edits into one row — they may want one.
  • Why is one line, concrete, no hedging. Not "seems unnecessary."
  • Order by value, not by verdict. Contradictions and unexecutable rules first, then unmet new behavior (H) and model-compensation (A), then duplication. Never rank ADDs last as a class — an instruction the new model needs and does not have is usually worth more than one stale line removed. KEEP rows go last, and only include a KEEP row when the user might expect it to be cut — otherwise it is noise.
  • Include KEEP rows for anything you considered and rejected, so the user can see the judgment and overrule it.

Tier 2 — full text per row

Below the table, one block per numbered row. Never truncate. No ellipsis.

### 1 · L89-113 · Sub-agent routing table — DELETE
Category E (unexecutable)
Evidence: `ls ~/.claude/agents/` -> only `pm-agent.md` exists

CURRENT
  <the exact lines, verbatim and complete>

PROPOSED
  <the exact replacement, verbatim and complete — or "(remove entirely)">

Every row cites its evidence: a verbatim quote from the live guide, a quoted line from your own system prompt, a named installed skill, or a command and its output. A row with no evidence does not belong in the table.

The prompt

End with exactly this shape:

Reply with the numbers you want:
  apply 1,3     test 1,3     apply all     apply none

test N hands those rows to houserules:test, which A/B's each rule against a real probe in separate headless runs before anything is written.

Do not ask an open-ended "what would you like to do?" — the user picks numbers.


Phase 6 — Apply

Only the numbers the user named. Nothing else.

  1. Back up first — non-negotiable. ~/.claude is usually not a git repo.
    cp "<target>" "<target>.bak-$(date +%Y-%m-%d-%H%M%S)"
  2. Apply with Edit. Preserve untouched sections byte-for-byte — do not reflow, reorder, or restyle prose you were not asked to change.
  3. Write MOVE extractions to their destination before removing from the source.
  4. Stamp the file:
    <!-- houserules: reviewed <date> against <model>. Re-run on the next model release. -->
  5. Show the diff and the backup path.
diff "<target>.bak-<stamp>" "<target>"

If the user picked a subset, say plainly which numbered rows were skipped so the remainder is not silently lost.


Anti-goals

  • Do not decide for the user. Produce the table; let them pick. A run that applies changes nobody selected is a bug.
  • Do not skip the briefing. Showing what Anthropic said is half the value.
  • Do not treat migration as pruning. Removing without adding leaves the file fitted to the old model. Work both lists.
  • Do not chase a line count. A 400-line CLAUDE.md of real preference is fine; a 40-line one full of scar tissue is not.
  • Do not delete on keyword match. Category G exists for this.
  • Do not truncate quoted current/proposed text. Full lines, always.
  • Do not hardcode model rules into this skill — including "obvious" ones. The next release moves the goalposts, and a stale pruner is worse than none.
  • Do not touch skills or hooks unless asked. This skill owns CLAUDE.md.
  • Do not write without a backup. Ever.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.