---

name: refactor description: "This skill should be used when the user asks to 'refactor this file', 'refactor this folder', 'apply coding rules', 'clean up code style', 'apply conventions', or wants files refactored to follow the project's and user's coding rules and conventions." user-invocable: true allowed-tools: Read, Edit, Write, Glob, Grep, Task, Bash(*)

Refactor Skill

Refactor one or more files to conform to the coding rules and conventions defined in the user's CLAUDE.md files and rule files.

Usage

Invoke with a file path, folder path, or glob pattern:

• /refactor src/components/Button/index.tsx
• /refactor src/pages/HomePage/
• /refactor src/api/

Or ask naturally:

• "Refactor this file to follow the rules"
• "Apply conventions to the components folder"
• "Clean up this code to match our style"

Workflow

Step 1: Gather Rules

Read all applicable rule sources to build a complete picture of conventions:

1. Project CLAUDE.md — Check for CLAUDE.md in the project root. Contains project-specific patterns, architecture notes, and conventions.
2. User global rules — Check ~/.claude/CLAUDE.md for user-wide preferences (communication style, code style, gatekeeper rules).
3. Rule files — Scan ~/.claude/rules/ and .claude/rules/ for language- and framework-specific rule files (e.g., react-vite.md, python.md, scientific-papers.md).

Identify which rule files are relevant based on the file types being refactored (e.g., .tsx files → load react-vite.md, .py files → load python.md).

Step 2: Analyze Target Files

Determine the scope of work:

• Single file: Read the file, identify all rule violations.
• Folder: Use Glob to find all source files in the folder. Read each file and identify violations.
• Pattern: Expand the glob pattern and process matching files.

For each file, check against relevant rules. Common areas to inspect:

For React/TypeScript files:

• BEM naming in CSS Modules
• classnames usage (no template literals for class concatenation)
• Path alias usage (@components/, @hooks/, etc. instead of relative imports)
• export default on index.tsx files
• Import order (React → third-party → aliased → types → styles)
• Pages must not define components inline
• Component folder structure (index.tsx + styles.module.css)

For Python files:

• Google Style Guide formatting (80 char lines, naming conventions)
• Google-style docstrings for public functions/classes
• Type hints using typing module (List, Dict, Optional, etc.)
• Import organization (stdlib → third-party → local)
• Specific exception handling (no bare except)

For CSS Module files:

• BEM convention (.block__element--modifier)
• No camelCase class names where BEM is expected

Step 3: Apply Refactoring

For each file, apply edits using the Edit tool. Make targeted, minimal changes — only fix rule violations, do not restructure logic or add features.

Priorities (apply in order):

1. Import organization and path aliases
2. Export style (export default)
3. Naming conventions (BEM, variable naming)
4. Class concatenation (classnames usage)
5. Docstrings and type hints
6. Code formatting

Step 4: Report

After refactoring, provide a concise summary:

• Files modified and key changes per file
• Any files skipped (already conforming)
• Any issues that require manual intervention (e.g., missing component folder structure, ambiguous naming)

Important Rules

• Minimal changes only. Fix rule violations. Do not refactor logic, add features, or "improve" code beyond what the rules require.
• Read before editing. Always read the file before making changes.
• Preserve behavior. Refactoring must not change runtime behavior.
• Skip conforming files. If a file already follows all rules, skip it.
• Ask when ambiguous. If a rule conflict exists or the correct refactoring is unclear, ask the user before proceeding.

Additional Resources

Reference Files

For the full text of coding rules that inform refactoring decisions:

• references/rule-sources.md — Guide to locating and prioritizing rule files