Refactor React Components with Composition Patterns

React Composition Patterns is a skill of guidelines for building flexible, maintainable React components. Its central idea is to avoid boolean prop proliferation by using compound components, lifting state and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale. It is sourced from the vercel-labs agent-skills repository.

The guidance is split into four rule categories, each with a filename prefix and an impact rating.

Component Architecture, rated HIGH, uses the architecture- prefix. It has two rules: do not add boolean props to customize behavior and use composition instead, and structure complex components with shared context.

State Management, rated MEDIUM, uses the state- prefix. Three rules cover it: the provider is the only place that knows how state is managed, a generic interface with state, actions and meta should be defined for dependency injection, and state should be moved into provider components so siblings can access it.

Implementation Patterns, rated MEDIUM, uses the patterns- prefix. It recommends creating explicit variant components instead of boolean modes, and using children for composition instead of renderX props.

React 19 APIs, rated MEDIUM, uses the react19- prefix. The single rule says not to use forwardRef, and to use use() instead of useContext(). The skill warns that this section applies to React 19 and later only.

Reference these guidelines when refactoring components that have many boolean props, building reusable component libraries, designing flexible component APIs, reviewing component architecture, or working with compound components and context providers.

Skip the react19- rules if your project is on React 18 or earlier. The skill's Limitations section adds three boundaries: use it only when the task clearly matches the scope described, do not treat its output as a substitute for environment-specific validation, testing or expert review, and stop and ask for clarification if required inputs, permissions, safety boundaries or success criteria are missing.

The input is a component, component API or code review that involves the patterns above. The skill works by pointing the agent to individual rule files that hold the detailed explanations and code examples. Each rule file contains a brief explanation of why it matters, an incorrect code example with an explanation, a correct code example with an explanation, and additional context and references.

The complete guide with all rules expanded is a compiled document named AGENTS.md. The output is guidance and recommended refactors that follow those rules, such as replacing a boolean-mode component with explicit variants or moving shared state into a provider.

React developers and component library authors who want consistent composition-based APIs, reviewers who check component architecture, and teams that let AI agents write or modify React code and want the agent to follow a documented set of conventions. The skill is marked safe in its metadata.