React Refactor
Apply a 40-rule React architectural refactor playbook when a solo builder’s UI has prop explosions, wrong folder layout, or performance smells before shipping the next feature.
Overview
React Refactor is an agent skill most often used in Build (also Ship review) that applies 40 categorized React architectural rules with smells, transforms, and safe refactoring steps.
Install
npx skills add https://github.com/pproenca/dot-skills --skill react-refactorWhat is this skill?
- 40 refactoring rules organized across 7 architecture categories with code smells and before/after patterns
- CRITICAL rules for interface segregation on props, feature colocation, render-props-to-hooks, and headless components
- Composition-over-props and push-client-boundaries guidance to cut nesting and unnecessary re-renders
- Each rule documents safe refactoring steps rather than one-off style opinions
- Covers state architecture, coupling, side effects, and refactoring safety alongside component structure
- 40 rules across 7 categories
- Version 1.1.0 (May 2026)
Adoption & trust: 562 installs on skills.sh; 157 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your React app grew feature by feature and now suffers from prop drilling, wrong file layout, and performance regressions you do not know how to untangle safely.
Who is it for?
Solo builders maintaining a mid-size React or Next.js frontend who want a checklist-driven refactor instead of guessing which patterns to fix first.
Skip if: Greenfield projects with no React code yet, or teams that only need lint autofixes without structural architecture guidance.
When should I use this skill?
Working in a React or Next.js repo with architectural smells, large refactors, or pre-merge UI review.
What do I get? / Deliverables
After the skill runs, you get prioritized architectural changes—colocation, hooks, composition, client boundaries—with explicit before/after guidance you can apply incrementally in the repo.
- Prioritized list of applicable rules with before/after code guidance
- Incremental refactor plan aligned to the seven rule categories
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build → frontend because the skill is an in-repo refactoring guide for React component and state architecture, not launch or ops tooling. Subphase frontend matches component props, hooks, client boundaries, and decomposition rules aimed at React UI codebases.
Where it fits
You are splitting a dashboard monolith and want the 40-rule checklist to decide colocation versus shared hooks first.
Before merging a large UI PR, you ask the agent to map changed files against interface-segregation and composition rules.
Production hotfixes keep reintroducing prop drilling, so you rerun targeted categories from the guide on the touched modules.
How it compares
Use instead of generic “clean up this component” chat prompts when you need a numbered rule set with documented transforms.
Common Questions / FAQ
Who is react-refactor for?
It is for solo and indie developers who own a React frontend and need systematic guidance on component architecture, hooks, and state—not one-off style tweaks.
When should I use react-refactor?
Use it during Build when refactoring features or folders, during Ship review before merging large UI changes, and whenever you see prop explosion, deep nesting, or misplaced client boundaries.
Is react-refactor safe to install?
Treat it like any third-party skill: review the Security Audits panel on this Prism page and scan the repo copy; the skill is documentation-driven and does not require shell or network by default.
SKILL.md
READMESKILL.md - React Refactor
# React **Version 1.1.0** React Refactor Best Practices May 2026 --- ## Abstract Architectural refactoring guide for React applications. Contains 40 rules across 7 categories covering component architecture, state architecture, hook patterns, component decomposition, coupling and cohesion, data and side effects, and refactoring safety. Each rule includes code smell indicators, before/after transforms, and safe refactoring steps. --- ## Table of Contents 1. [Component Architecture](references/_sections.md#1-component-architecture) — **CRITICAL** - 1.1 [Apply Interface Segregation to Component Props](references/arch-interface-segregation.md) — CRITICAL (prevents 30-50% of unnecessary re-renders from unrelated prop changes) - 1.2 [Colocate Files by Feature Instead of Type](references/arch-feature-colocation.md) — CRITICAL (reduces cross-directory navigation by 70%, makes features self-contained) - 1.3 [Convert Render Props to Custom Hooks](references/arch-render-props-to-hooks.md) — CRITICAL (eliminates 2-4 levels of nesting, improves readability) - 1.4 [Extract Headless Components for Logic Reuse](references/arch-headless-pattern.md) — CRITICAL (enables 5x more reuse scenarios for the same behavior) - 1.5 [Prefer Composition Over Props Explosion](references/arch-composition-over-props.md) — CRITICAL (reduces prop count by 50-70%, enables independent extension) - 1.6 [Push Client Boundaries to Leaf Components](references/arch-push-client-low.md) — HIGH (keeps 60-80% of component tree server-rendered) - 1.7 [Separate Container Logic from Presentational Components](references/arch-container-presentational.md) — CRITICAL (enables independent testing and Storybook preview) - 1.8 [Use Compound Components for Implicit State Sharing](references/arch-compound-components.md) — CRITICAL (reduces component API surface by 60%, eliminates prop drilling) 2. [State Architecture](references/_sections.md#2-state-architecture) — **CRITICAL** - 2.1 [Colocate State with Components That Use It](references/state-colocate-with-consumers.md) — CRITICAL (reduces prop passing by 60%, improves component isolation) - 2.2 [Derive Values Instead of Syncing State](references/state-derive-dont-sync.md) — CRITICAL (eliminates double-render cycle, prevents sync drift) - 2.3 [Lift State Only When Multiple Components Read It](references/state-lift-only-when-shared.md) — CRITICAL (eliminates unnecessary parent re-renders, clearer ownership) - 2.4 [Use Context for Rarely-Changing Values Only](references/state-context-for-static.md) — CRITICAL (5-50x fewer re-renders for context consumers) - 2.5 [Use State Machines for Complex UI Workflows](references/state-machines-for-workflows.md) — CRITICAL (reduces valid states from 2^n to exactly N defined states) - 2.6 [Use URL Parameters as State for Shareable Views](references/state-url-as-state.md) — CRITICAL (enables deep linking, back/forward navigation, state sharing) - 2.7 [Use useReducer for Multi-Field State Transitions](references/state-reducer-for-complex.md) — CRITICAL (eliminates impossible states, centralizes transition logic) 3. [Hook Patterns](references/_sections.md#3-hook-patterns) — **HIGH** - 3.1 [Avoid Object and Array Dependencies in Custom Hooks](references/hook-avoid-object-deps.md) — HIGH (prevents effect re-execution on every render) - 3.2 [Compose Hooks Instead of Nesting Them](references/hook-composition-over-nesting.md) — HIGH (flattens dependency graph, eliminates hidden coupling) - 3.3 [Extract Logic into Custom Hooks When Behavior Is Nameable](references/hook-extract-when-nameable.md) — HIGH (makes component 40-60% shorter, behavior self-documenting) - 3.4 [Follow Hook Naming Conventions for Discoverability](references/hook-naming-conventions.md) — HIGH (reduces codebase navigation time by 40%) - 3.5 [Keep Custom Hooks to a Single Responsibility](references/hook-single-responsibility.md) — HIGH (3× faster to test, 2× wider reu