refactor

Analyze a code directory and generate a design document with an improvement plan.

4|2|Updated Jan 30, 2026
One-click install
npx skills add https://github.com/alexanderguy/skills --skill refactor-alexanderguy
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refactor
Source: https://github.com/alexanderguy/skills/tree/main/skills/refactor
Command: npx skills add https://github.com/alexanderguy/skills --skill refactor-alexanderguy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps you understand an existing codebase and turn vague refactor ideas into a clear, structured design and execution-ready improvement plan.

Core Features & Use Cases

  • Design-document the current code: Summarizes purpose, key components, responsibilities, and how data flows.
  • Surface risks with evidence: Captures factual observations like complexity, inconsistencies, and potential concerns before prescribing changes.
  • Plan improvements collaboratively: Grounds proposed changes in existing philosophy principles and iterates with user priorities until aligned.

Quick Start

Analyze the directory you want to refactor, then request a design document plus an improvement plan that another agent can execute.

Frequently Asked Questions about refactor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a refactoring plan for legacy code?

A codebase refactoring plan starts with analyzing your directory to map data flow and components, then capturing factual observations on complexity to produce an execution-ready improvement plan with prioritized steps.

How do I generate design documentation for an existing codebase?

You can generate design documentation by analyzing the target directory to produce a structured overview of components, data flow, dependencies, and patterns, capturing factual observations before prescribing changes.

What is the best way to plan code modernization for a messy directory?

Planning code modernization involves analyzing the directory to surface factual observations like complexity and inconsistencies, then generating a prioritized improvement plan that provides guidance for structural transformations.

Can I use ast-grep for structural code transformations during a refactor?

Yes, ast-grep is recommended for structural code transformations during a refactor, specifically guided by the generated improvement plan to ensure changes align with the documented architecture and design patterns.

How do I align my team on code maintainability improvements?

You align your team on code maintainability improvements by generating a structured design document that surfaces factual observations, then iterating the improvement plan with user priorities until collaboratively aligned.