Code Refactoring Workflow
luongnv89/claude-howto
Guides systematic, test-backed refactoring in the style of Martin Fowler, moving through research, planning and small incremental changes with your approval at each phase.
Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements.
Install Modernization Assessment
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessment --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/modernization-assessment .claude/skills/modernization-assessment && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .claude/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessmentType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessment --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.github/skills/modernization-assessment .agents/skills/modernization-assessment && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .agents/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessment --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.github/skills/modernization-assessment .cursor/skills/modernization-assessment && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .cursor/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/EmeaAppGbb/spec2cloud.git --path .github/skills/modernization-assessment--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessment --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.github/skills/modernization-assessment .gemini/skills/modernization-assessment && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .gemini/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessmentInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .github/skills && cp -r skills-src/.github/skills/modernization-assessment .github/skills/modernization-assessment && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .github/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install EmeaAppGbb/spec2cloud modernization-assessment --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/EmeaAppGbb/spec2cloud.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.github/skills/modernization-assessment .opencode/skills/modernization-assessment && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "modernization-assessment" agent skill from https://github.com/EmeaAppGbb/spec2cloud/tree/vNext/.github/skills/modernization-assessment into .opencode/skills/modernization-assessment/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "modernization-assessment", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
modernization-assessment- GitHub stars
- 100
- Token cost
- ~1.9k tokens
- SKILL.md length
- 717 words
- Files
- 1
- Skills in repo
- 38
- Repo updated
- First seen
- Licence
- MIT
At a glance
Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements.
- Tasks that involve Legacy modernization
- SKILL.md covers Role, Inputs, Adaptive Depth Levels and Assessment Categories, plus 5 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
- Tasks that involve Architecture decision records
What it does
Modernization Assessment is an agent skill from EmeaAppGbb/spec2cloud. Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements. Adaptive depth — starts surface-level, escalates based on findings. Produces ADRs for significant decisions.
Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Legacy modernization, Architecture decision records and Technical debt. The licence is MIT.
When your agent uses it
- Tasks that involve Legacy modernization
- Tasks that involve Architecture decision records
- Tasks that involve Technical debt
Example prompts
- “/modernization-assessment”
What it can do on your machine
Read from SKILL.md and the folder at commit 8e76618. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Modernization Assessment loads about 1.9k tokens when it runs. Until then it costs about 67 tokens; SKILL.md has 717 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from EmeaAppGbb/spec2cloud at commit 8e76618, republished under its MIT licence (© EmeaAppGbb). 717 words, ~1,852 tokens.
Download SKILL.mdSave it as
.claude/skills/modernization-assessment/SKILL.md (or your agent's skills folder).- name
- modernization-assessment
- description
- Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements. Adaptive depth — starts surface-level, escalates based on findings. Produces ADRs for significant decisions.
Role
You are a modernization analyst. Your job is to systematically evaluate an existing codebase and identify what CAN be improved — not what MUST be. You produce a structured assessment that helps the user prioritize modernization work based on severity, effort, and impact.
You are activated when the user selects the modernize path. You do not run automatically.
Inputs
specs/docs/technology/*— Technology inventory from extraction phasespecs/docs/architecture/*— Architecture documentation from extraction phasespecs/docs/dependencies/*— Dependency manifests and lock files- Source code access for pattern analysis
Adaptive Depth Levels
This assessment uses adaptive depth — start at Level 1 and escalate based on findings.
Level 1 — Surface Scan
Perform a fast, broad sweep:
- Dependency age analysis: Check package manifests against latest versions. Flag dependencies more than 2 major versions behind.
- Deprecated API usage: Scan for known deprecated patterns in the primary language/framework.
- Linter warnings: Run or review existing linter output for systemic issues.
- EOL runtime detection: Flag runtimes, frameworks, or platforms past end-of-life.
- Quick config review: Check for obviously outdated configuration patterns (e.g., legacy build tools, abandoned plugins).
Estimated time: 5–15 minutes of analysis.
Level 2 — Moderate Analysis
Triggered when Level 1 finds >5 critical or high-severity items:
- Code complexity metrics: Identify high-complexity modules (cyclomatic complexity, function length, file size).
- Pattern anti-patterns: Detect god classes, circular dependencies, copy-paste duplication, deep nesting.
- Coupling analysis: Map module dependencies and identify tightly coupled components that resist change.
- Test coverage gaps: Identify untested critical paths and modules with zero coverage.
- Build pipeline review: Evaluate CI/CD configuration for outdated practices, missing stages, slow steps.
Estimated time: 15–45 minutes of analysis.
Level 3 — Deep Assessment
Triggered when Level 2 finds architectural concerns (e.g., monolithic coupling, scalability limits, missing abstraction layers):
- Architectural debt assessment: Evaluate whether the current architecture supports planned growth.
- Performance anti-patterns: Identify patterns known to degrade at scale (synchronous chains, missing caching layers, N+1 queries).
- Scalability limits: Assess stateful components, single points of failure, and horizontal scaling barriers.
- Migration path analysis: For each major finding, sketch a migration path with incremental steps.
- Dependency risk matrix: Evaluate bus factor, maintenance status, and license risk for critical dependencies.
Estimated time: 45–90 minutes of analysis.
Escalation Rules
Level 1 findings > 5 critical/high → auto-escalate to Level 2
Level 2 finds architectural concerns → escalate to Level 3
User can force any level with: "run modernization assessment at level 3"Assessment Categories
Organize all findings into these categories:
| Category | What to Evaluate |
|---|---|
| Dependencies | Version currency, CVEs, maintenance status, license compatibility |
| Patterns | Code patterns, anti-patterns, duplication, complexity |
| Architecture | Modularity, coupling, scalability, separation of concerns |
| Testing | Coverage, test quality, test infrastructure, missing test types |
| DevOps/CI | Build pipeline, deployment process, environment management |
| Documentation | Code docs, API docs, runbooks, architecture decision records |
Show full SKILL.md (303 more words)Show less
Severity Ratings
- Critical: Blocking issues or active security vulnerabilities. Must be addressed before any modernization.
- High: Significant technical debt that will impede modernization efforts. Should be addressed.
- Medium: Improvement opportunities that would benefit the codebase. Nice to fix.
- Low: Cosmetic or minor issues. Address opportunistically.
Each finding includes:
- Category and subcategory
- Severity rating
- Description of the issue
- Location(s) in codebase
- Suggested remediation
- Estimated effort (hours/days/weeks)
Output Format
Generate specs/assessment/modernization.md with this structure:
# Modernization Assessment
## Summary
- Assessment depth: Level [1/2/3]
- Total findings: [N]
- Critical: [N] | High: [N] | Medium: [N] | Low: [N]
- Escalation triggered: [yes/no — reason]
## Findings by Category
### Dependencies
| # | Severity | Finding | Location | Remediation | Effort |
|---|----------|---------|----------|-------------|--------|
### Patterns
(same table format)
### Architecture
(same table format)
### Testing
(same table format)
### DevOps/CI
(same table format)
### Documentation
(same table format)
## Modernization Roadmap (if Level 2+)
Suggested sequencing of improvements based on dependencies between findings.
## Decision Points
Items that require user decision — linked to generated ADRs.ADR Triggers
When the assessment reveals a decision point, generate an ADR using the adr skill. Common triggers:
- Framework upgrade vs replacement: When a framework is significantly outdated and both paths are viable.
- Architecture evolution: When findings suggest a shift (e.g., monolith to modular monolith).
- Dependency substitution: When a critical dependency is unmaintained and alternatives exist.
- Testing strategy change: When the current testing approach has fundamental gaps.
Each ADR should reference the specific assessment findings that triggered it.
Important Notes
- Assessment identifies what CAN be improved. The user decides priority and sequencing.
- Do not assume all findings must be fixed. Present options, not mandates.
- Effort estimates are rough guidance, not commitments.
- If extraction outputs are incomplete, note gaps rather than guessing.
- Preserve existing functionality descriptions — this is analysis, not transformation.
Mandatory Completion Checklist
The orchestrator MUST verify ALL of the following before marking modernization-assessment as complete:
-
specs/assessment/modernization.mdexists with: executive summary, findings by category, severity ratings, and effort estimates - Every finding has a severity level (critical / high / medium / low) and an estimated effort
- At least one ADR exists in
specs/adrs/for each significant architecture decision surfaced - Findings reference specific files, line numbers, or patterns from the extraction outputs
- State JSON and audit log are updated
BLOCKING: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items before advancing to planning.
© EmeaAppGbb, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .github/skills/modernization-assessment of EmeaAppGbb/spec2cloud.
Open the folder on GitHubat commit 8e76618
Compare with similar skills
Modernization Assessment next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Modernization Assessment this skillEmeaAppGbb/spec2cloud | 100 | — | ~1.9k | Automated safety check: Pass | MIT | |
| Code Refactoring Workflowluongnv89/claude-howto | 42k | — | ~3.1k | Automated safety check: Pass | MIT | |
| Cto AdvisorIbrahim-3d/orchestrator-supaconductor | 380 | 4 repos | ~2.4k | Automated safety check: Pass | MIT | |
| Rails Upgrade Assistantombulabs/claude-code_rails-upgrade-skill | 389 | — | ~2.7k | Automated safety check: Pass | MIT | |
| Fowler-Style Refactoringlhfer/claude-howto-zh-cn | 2.3k | — | ~156 | Automated safety check: Pass | MIT | |
| Refactoring Skill (Vietnamese)luongnv89/claude-howto | 42k | — | ~3.1k | Automated safety check: Pass | MIT |
Similar skills
Cto Advisor
Ibrahim-3d/orchestrator-supaconductor
Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.
Rails Upgrade Assistant
ombulabs/claude-code_rails-upgrade-skill
Analyzes a Rails app and builds an upgrade report with breaking changes, deprecations and step-by-step migration guides, one version at a time from Rails 2.3 through 8.1.
Fowler-Style Refactoring
lhfer/claude-howto-zh-cn
基于 Martin Fowler 方法论做系统化重构。Use when users ask to refactor code, improve structure, reduce technical debt, clean up legacy code, or improve maintainability.
Refactoring Skill (Vietnamese)
luongnv89/claude-howto
Vietnamese edition of a systematic refactoring skill based on Martin Fowler's book, working in approved phases with small, test-backed changes.
Legacy Modernizer
Jeffallan/claude-skills
Plans incremental migrations of aging systems with the strangler fig pattern, using dependency maps, rollback plans, characterization tests and gradual traffic shifts.
More from EmeaAppGbb/spec2cloud
All 38 skills in this repoAzure Deployment
EmeaAppGbb/spec2cloud
Provision Azure infrastructure, deploy to Azure Container Apps, and verify via smoke tests.
Contract Generation
EmeaAppGbb/spec2cloud
Generate API contracts, shared TypeScript types, and infrastructure resource definitions from Gherkin scenarios and test files.
Ddd Modeling
EmeaAppGbb/spec2cloud
Create Domain-Driven Design proposals from product specs or brownfield extraction outputs.
Implementation
EmeaAppGbb/spec2cloud
Write application code to make failing tests pass using contract-driven, slice-based architecture.
Spec Refinement
EmeaAppGbb/spec2cloud
Review PRDs and FRDs through product and technical lenses. An agent skill from EmeaAppGbb/spec2cloud.
State Management
EmeaAppGbb/spec2cloud
Read, write, and maintain .spec2cloud/state.json across phases and increments.
Related
Categories
Questions about Modernization Assessment
What does Modernization Assessment do?
Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements. Modernization Assessment is an agent skill from EmeaAppGbb/spec2cloud. Assess codebase for modernization opportunities — tech debt, deprecated dependencies, outdated patterns, architectural improvements.
When should I use Modernization Assessment?
Modernization Assessment fits situations like: tasks that involve Legacy modernization; tasks that involve Architecture decision records; tasks that involve Technical debt.
How do I install Modernization Assessment in Claude Code?
Run `npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a claude-code`. Or copy the skill folder (.github/skills/modernization-assessment in EmeaAppGbb/spec2cloud) into .claude/skills/modernization-assessment in your project. Claude Code loads it when a task matches its description.
How do I install Modernization Assessment in Codex?
Run `npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a codex`. Or copy the skill folder (.github/skills/modernization-assessment in EmeaAppGbb/spec2cloud) into .agents/skills/modernization-assessment in your project. Codex loads it when a task matches its description.
Can I use Modernization Assessment in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add EmeaAppGbb/spec2cloud --skill modernization-assessment -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/modernization-assessment, .gemini/skills/modernization-assessment, .github/skills/modernization-assessment and .opencode/skills/modernization-assessment in your project.
What does Modernization Assessment need to run?
SKILL.md names no scripts, command-line tools or credentials: Modernization Assessment is instructions for the agent only.
Does Modernization Assessment access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Modernization Assessment safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Modernization Assessment use?
Modernization Assessment is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Modernization Assessment use?
About 1.9k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Modernization Assessment?
Skills that share tags, products or a category with Modernization Assessment: Code Refactoring Workflow (luongnv89/claude-howto, 42k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 380 stars), Rails Upgrade Assistant (ombulabs/claude-code_rails-upgrade-skill, 389 stars) and Fowler-Style Refactoring (lhfer/claude-howto-zh-cn, 2.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Modernization Assessment?
EmeaAppGbb (a GitHub organization) maintains it in EmeaAppGbb/spec2cloud, which has 100 GitHub stars. The repository holds 38 skills in this directory. The repository was last updated on April 16, 2026.
Source: EmeaAppGbb/spec2cloud on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.