[Skill] Create refactoring-advisor skill for analyzing codebases and proposing refactoring plans

a

Summary

Create a skill that enables the agent to act as a senior software architect agent: scanning a repository for structural problems — at the class, module, function, and dependency level — diagnosing root causes, and producing structured refactoring proposals that a separate implementation agent can execute. The skill covers the full spectrum of refactoring concerns, not just large classes.

The skill should have a strong bias toward dependency injection as a default decoupling technique, complemented by classical design patterns and refactoring strategies when appropriate.

---

Motivation

Technical debt accumulates at every level of a codebase: god classes, tangled modules, duplicated logic, deep coupling, leaky abstractions, bloated functions, circular dependencies, and more. Developers often sense something is wrong but lack the time or architectural perspective to produce a concrete, prioritized remediation plan.

This skill fills that gap: it gives Claude a structured methodology to audit any codebase, flag problems across all levels of granularity, and output actionable refactoring specs — ready for a human or an implementation agent to pick up.

---

Skill Specification

Name: refactoring-advisor

Description (for triggering):

Analyze a codebase to identify structural problems and propose concrete refactoring plans using design patterns, dependency injection, and established refactoring techniques. Use this skill whenever the user asks to improve code structure, reduce complexity, break apart large or tangled code, decouple modules, introduce dependency injection, eliminate duplication, simplify deeply nested logic, resolve circular dependencies, improve testability, or audit a repository for code smells at any level (function, class, module, package). Also trigger when a user mentions terms like "refactor", "code smells", "technical debt", "god class", "spaghetti code", "too coupled", "hard to test", "extract method", "reduce complexity", or "clean up this codebase". This skill produces analysis and proposals only — it does not write implementation code.

Trigger Contexts:

• "Help me refactor this codebase"
• "This code is a mess, where do I start?"
• "Scan this repo for code smells"
• "How can I make this easier to test?"
• "These modules are too tightly coupled"
• "Introduce dependency injection into this project"
• "Create a refactoring plan for [class/module/package]"
• "This function is way too long"
• "We have circular dependencies everywhere"
• "There's a ton of duplicated logic across these files"
• "What design patterns should I apply here?"
• "Audit this repo for technical debt"

---

Skill Behavior — Three Phases

Phase 1 — Discovery

The agent scans the repository and flags problems at every level of granularity.

Function-level signals:

Signal	Threshold
Lines of code	> ~50
Parameters	> 4–5
Nesting depth	> 3 levels
Cyclomatic complexity	high branch count
Mixed abstraction levels	I/O + logic + formatting in one fn

---

Acceptance Criteria

• [ ] SKILL.md is under 500 lines, with reference docs for deeper content
• [ ] Skill triggers reliably on phrases like "refactor", "code smells", "technical debt", "too coupled", "hard to test", "simplify", "dependency injection"
• [ ] Discovery phase covers functions, classes, modules, and cross-cutting concerns — not just classes
• [ ] Diagnosis maps each item to specific named code smells
• [ ] Every proposal includes a DI evaluation (recommends injection where applicable, explicitly notes when not needed)
• [ ] Proposals are specific (naming functions, methods, fields, file paths, line ranges) — not generic advice
• [ ] Output follows the structured template consistently
• [ ] Proposals end with a prioritized action plan (impact vs. effort)
• [ ] Skill works across at least Java, Python, TypeScript, and C#
• [ ] No implementation code is produced — only architectural plans
• [ ] In the PR, there is an example of running the skill on a codebase

---

Start by reviewing the proposed SKILL.md structure and the acceptance criteria, including the requirement for reference docs when content exceeds 500 lines. Done means the skill covers discovery and diagnosis across functions, classes, modules, and cross-cutting concerns, produces structured plans without implementation code, supports Java, Python, TypeScript, and C#, and includes a PR example.