team-refactor_skill

Overview

This skill automates creation and orchestration of a specialist Agent Team to plan large-scale code refactors. It detects the refactoring scope, analyzes the codebase to classify the refactor type, selects the right experts, and runs them in parallel to produce a safe, incremental refactoring plan. The lead agent synthesizes findings into dependency maps, risk assessments, and rollout steps.

How this skill works

The skill parses the provided target (file, directory, PR, commit, diff, or free-text goal) to determine scope and refactor type. It runs a pre-analysis to classify signals (extract/split, rename/restructure, pattern change, dependency update, performance) and applies a selection matrix to spawn only the required specialists. Each specialist runs in parallel with the full target context and returns focused findings; the lead agent then synthesizes those results into a step-by-step plan with rollback points and test checkpoints.

When to use it

• Preparing a coordinated, multi-person refactor across modules or services
• Refactoring legacy or tightly coupled code where risk and history matter
• Upgrading frameworks, libraries, or language versions with potential breaking changes
• Restructuring public APIs or making pattern-level architecture changes
• Planning performance optimizations that touch many components

Best practices

• Provide a clear scope argument (PR, commit, diff, file path, or concise goal) to avoid ambiguous analysis
• Prefer including more specialists if uncertain—thoroughness reduces missed risks
• Ensure repository history is available to the tool for archeological analysis (git access)
• Maintain an up-to-date test suite before running the plan; add critical tests early
• Use feature flags and small incremental steps in the migration plan to minimize blast radius

Example use cases

• Split a monolithic service into smaller modules while preserving public API contracts
• Rename and reorganize a package hierarchy across multiple repositories with compatibility shims
• Migrate callback-based code to async/await across a large codebase with staged rollout
• Upgrade a framework major version and produce a migration plan with compatibility checks and test gates
• Optimize a hot code path by analyzing coupling, measuring impact, and sequencing safe changes