code modernization — Agent Skill

Code Modernization

Point Claude at a legacy codebase and get four things: an understanding of what it is and what it does, a plan you approve, the modernized code, and proof that the new code behaves like the old. It works with any language and any kind of move: a newer version of the same technology, a rewrite in another one, or a rebuild on a new architecture.

Install

You need Claude Code. Then:

/plugin install code-modernization@claude-plugins-official

Some steps start many agents at once, so expect real usage on a large system (see *What to expect*). Start with one module or one unit as a pilot, not the whole estate.

Start here

Open a folder for the work and type /code-modernization:modernize. It asks what you want to do with your code (a couple of short questions), finds the code, writes your answers down once, shows the road ahead, and gives you the exact first command. Every later command reads what you said, so nothing is asked twice. Not sure what you want? Choose *Understand it first*: you get the assessment, the map, the business rules and a plan, and no code is rebuilt.

To go step by step instead, point the first command at your code and follow the "next step" line each command ends with:

/code-modernization:modernize-preflight <name> --source <path to your code>
/code-modernization:modernize-status <name>       # where am I, and what is next: run it any time

<name> is a short label of your choice (letters, digits, -, _). --source makes a link at legacy/<name> and copies nothing, so a huge repository stays where it is. Nothing edits your legacy source. Commands write only to analysis/<name>/ and modernized/ (a build check writes build output where your build normally does), and each refreshes analysis/<name>/REPORT.html: one page, with everything found so far, that you can open or share. A few steps need someone who knows how the system is built and run, so bring an engineer for the first questions.

The path

Each step stands alone, so you can stop and review after any of them.

| Step | Command | What you get | | --- | --- | --- | | 0 | modernize | Say what you want. Writes INTENT.md; every later command reads it. | | 1 | modernize-preflight <name> [target-stack] [--source <path>] | Is the environment ready? Asks five questions only a person can answer (is this the whole system or a slice, can it build and test here, is there custom build tooling, has anyone tried before, is anything off limits), proves a build works on this code, and finds missing source. | | 2 | modernize-assess <name> | What am I dealing with: inventory, complexity, debt, security, and a recommended pattern. | | 3 | modernize-map <name> | The structure: dependencies, data flow, entry points and business flows, as an interactive map. | | 4 | modernize-extract-rules <name> | The business rules as testable Given/When/Then cards with file:line citations, each re-checked by a second agent. | | 4b | modernize-review <name> | A person confirms or corrects the rules that look wrong. Your answers reach the plan and the build. With the live pane on, /modernize-review-pane does the same one card at a time. | | 5 | modernize-brief <name> [target-stack] | The phased plan a steering committee approves. Nothing is built until you approve it. | | 6 | uplift, transform or reimagine | The build (see below). | | 7 | modernize-verify <name> | The proof. An independent re-check with one verdict per module. | | 8 | modernize-harden <name> | A security scan of the legacy system with a reviewed patch you apply yourself. |