refactor
Analyzes code for technical debt and structural issues to make codebases easier for AI agents to navigate.
Install
mkdir -p .claude/skills/refactor-pageloom && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/12250" && unzip -o skill.zip -d .claude/skills/refactor-pageloom && rm skill.zipInstalls to .claude/skills/refactor-pageloom
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Refactor Agent - Identify refactoring opportunities and technical debtKey capabilities
- →Identify god modules (files >500 lines) and scattered concepts.
- →Detect code duplication across functions and files.
- →Flag complex functions (functions >50 lines, nesting >3 levels, >5 parameters).
- →Identify inconsistent patterns like mixed naming conventions or different error handling.
- →Find dead code such as unused imports or unreachable paths.
- →Report refactoring opportunities and technical debt in `.claude/ISSUES.md`.
How it works
The skill systematically scans a codebase to identify refactoring opportunities and technical debt by analyzing file structure, code duplication, function complexity, and inconsistent patterns, then reports findings in a structured format.
Inputs & outputs
When to use refactor
- →Identify god classes for decomposition
- →Remove dead code and unused imports
- →Standardize error handling across modules
About this skill
Refactor Agent - Code Quality Analysis Mode
Identify refactoring opportunities and technical debt. Primary goal: make code easy for Claude to traverse.
Quick Reference
- Reads: Codebase,
.claude/REFACTOR_HISTORY.md - Writes: .claude/ISSUES.md, REFACTOR_HISTORY.md
- Can commit: No
Before You Start
- Read
.claude/THOUGHT_ERRORS.mdto avoid past mistakes - Read
.claude/REFACTOR_HISTORY.mdto see what's been scanned recently
Primary Priority: Claude Traversability
| Factor | Target | Why |
|---|---|---|
| File size | <500 lines, <300 preferred | Large files don't fit in context |
| Module boundaries | Single responsibility | One file = one concept |
| Consistent patterns | Same everywhere | No re-learning per file |
| Self-documenting | Names match contents | Navigate without exploration |
Categories
1. File Structure (Highest Priority)
- God modules: Files >500 lines handling multiple concerns
- Scattered concepts: Related code spread across many files
- Inconsistent patterns: Similar modules structured differently
2. Code Duplication
- Copy-pasted logic across functions/files
- Repeated validation, error handling, data transformations
3. Complex Functions
- Functions >50 lines
- Nesting >3 levels
- Functions with >5 parameters
4. Inconsistent Patterns
- Mixed naming conventions
- Different error handling approaches
- Inconsistent return types
5. Dead Code
- Unused imports
- Unreachable code paths
- Commented-out code blocks
6. Poor Abstractions
- God classes doing unrelated things
- Premature abstractions (one use case)
- Missing abstractions (scattered related code)
7. Tight Coupling
- Circular dependencies
- Hardcoded configuration
- Business logic mixed with infrastructure
8. Quality of Test Code
- Nested patch pyramids
- Duplicated setup across tests
- Missing docstrings
- Opportunities for parametrization
See .claude/references/refactor-patterns.md for detailed patterns and examples.
Workflow
1. Review History
Check .claude/REFACTOR_HISTORY.md to understand:
- What was scanned recently
- What areas are overdue
- Recurring patterns
2. Ask User
- Scope: Full codebase, specific module, or test code?
- Focus: All categories or specific concern?
- Depth: Quick (high-impact), standard (medium+), or deep (comprehensive)?
3. Systematic Scanning
File Structure (do first):
- Measure file sizes (flag >500 lines)
- Count public functions per file (flag >15)
- Check if related concepts are co-located
Per Category:
- Use grep/glob to find patterns
- Document exact file:line references
- Assess impact (high/medium/low)
4. Report to .claude/ISSUES.md
5. Update History
After scanning, update .claude/REFACTOR_HISTORY.md with:
- Date and scope
- Categories examined
- Key findings
- Issues logged
Thresholds
| Metric | Flag | Critical |
|---|---|---|
| File lines | >500 | >1000 |
| Function lines | >50 | >100 |
| Nesting levels | >3 | >5 |
| Parameters | >5 | >7 |
| Imports from same module | >3 | - |
Issue Format
## [REFACTOR] [Category]: [Brief Description]
**Found in:** [File:line]
**Impact:** High/Medium/Low
**Category:** [File Structure | Duplication | Complexity | etc.]
**Description:** [What's wrong]
**Evidence:** [Code snippet]
**Why It Matters:** [Maintainability, bugs, development speed]
**Suggested Refactoring:** [Specific approach]
**Files Affected:** [List]
Example:
```python
# Before:
[problematic code]
# After:
[improved code]
## What You Cannot Do
- No code fixes (log issues for `/dev`)
- No test writing (that's `/test`)
- No subjective opinions (back with evidence)
- No bikeshedding (focus on impactful improvements)
## Start Here
1. Read `.claude/REFACTOR_HISTORY.md`
2. Ask about scope, focus, and depth
3. Recommend areas based on history
When not to use it
- →When the user needs code fixes to be applied directly.
- →When the user needs test code to be written.
- →When the user wants subjective opinions without evidence.
Limitations
- →The skill does not apply code fixes.
- →The skill does not write test code.
- →The skill does not provide subjective opinions.
How it compares
This skill provides a systematic, evidence-based analysis of code quality with specific thresholds for flagging issues, focusing on 'Claude Traversability,' which is more structured and objective than a manual code review.
Compared to similar skills
refactor side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| refactor (this skill) | 0 | 4mo | No flags | Advanced |
| effective-go | 323 | 9mo | No flags | Beginner |
| solid-principles | 57 | 9mo | No flags | Intermediate |
| typescript-review | 39 | 2mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
effective-go
openshift
Apply Go best practices, idioms, and conventions from golang.org/doc/effective_go. Use when writing, reviewing, or refactoring Go code to ensure idiomatic, clean, and efficient implementations.
solid-principles
SmidigStorm
Enforce SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) in object-oriented design. Use when writing or reviewing classes and modules.
typescript-review
metabase
Review TypeScript and JavaScript code changes for compliance with Metabase coding standards, style violations, and code quality issues. Use when reviewing pull requests or diffs containing TypeScript/JavaScript code.
ast-grep
ast-grep
Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.
serena
massgen
This skill provides symbol-level code understanding and navigation using Language Server Protocol (LSP). Enables IDE-like capabilities for finding symbols, tracking references, and making precise code edits at the symbol level.
typescript
lobehub
TypeScript code style and optimization guidelines. Use when writing TypeScript code (.ts, .tsx, .mts files), reviewing code quality, or implementing type-safe patterns. Triggers on TypeScript development, type safety questions, or code style discussions.