Preface¶

In React projects, as components grow more complex, they tend to accumulate a slew of boolean props: isThread, isEditing, isDMThread, showAttachments, and so on. Every additional toggle doubles the number of possible states and bloats the conditional branches. Maintaining such code is already difficult for human developers, and letting AI coding assistants modify these components will only make the logic more convoluted over time.

Vercel has released a set of Agent Skills named composition-patterns in the vercel-labs/agent-skills repository (declared as vercel-composition-patterns in SKILL.md, version 1.0.0, MIT licensed). Instead of teaching isolated syntax, it translates the architectural principle of composition over configuration into executable guidelines for AI agents: avoid spreading boolean props, use compound components, lift state up to providers, and use children for composition instead of a pile of renderX callbacks. This article introduces what it is, how to install it, and how to use it, based on the official SKILL.md, AGENTS.md, and skills.sh documentation.

What It Is¶

The composition-patterns skill is a React composition pattern guide for AI coding agents. The official summary states it clearly: use compound components, lift state up, compose internal implementations, and avoid spreading boolean props, making codebases easier to modify for both humans and AI as they scale.

It is hosted in the vercel-labs/agent-skills repository, with authorship attributed to Vercel (metadata.author: vercel). The documentation is targeted at agents/LLMs that maintain, generate, or refactor React codebases, and is also human-readable, but its optimization goal is automation and consistency. The full set of rules is compiled in AGENTS.md, with individual rules stored in the rules/ directory, categorized into four priority tiers.

It is suitable for these scenarios:
- Refactoring components with a large number of boolean props
- Building reusable component libraries
- Designing flexible component APIs
- Reviewing component architecture
- Working with compound components or Context Providers

Core Features and Highlights¶

The official rules are grouped into four priority tiers (consistent with SKILL.md / AGENTS.md):

1. Component Architecture (HIGH)¶

Avoid Boolean Props Diffusion (architecture-avoid-boolean-props, marked CRITICAL impact): Do not use toggles like isThread or isEditing to customize behavior. Every boolean prop multiplies the number of possible states. The correct approach is to split components into explicit variants, such as ChannelComposer, ThreadComposer, and EditComposer, each combining the required child components.

Use Compound Components (architecture-compound-components): For complex components, use a composite structure with a shared Context. Child components consume state from the Context instead of passing props through multiple layers. Export components in the form of Composer.Provider / Composer.Frame / Composer.Input, allowing callers to assemble them as needed.

2. State Management (MEDIUM)¶

• Decouple State and UI (state-decouple-implementation): Only the Provider should know whether state comes from useState, Zustand, or server synchronization; the UI only consumes the Context interface.
• Generic Context Interface (state-context-interface): Agree on three parts for the Context: state / actions / meta, to facilitate dependency injection; the same UI can be attached to different Providers.
• Lift State Up to Providers (state-lift-state): Keep state trapped inside visual components no longer. Buttons and previews at the same level or even “outside the frame” can read and write state without prop drilling or awkward refs.

3. Implementation Patterns (MEDIUM)¶

• Explicit Variants (patterns-explicit-variants): Create ThreadComposer and EditComposer instead of a single Composer with a pile of mode booleans.
• Prefer Children Over Render Props (patterns-children-over-render-props): Compose UIs using composition instead of callback props like renderHeader or renderFooter.

4. React 19 APIs (MEDIUM)¶

Only applicable for React 19+. The official clarification: stop writing forwardRef; ref can be used as a regular prop; prefer use() over useContext() (and use() supports conditional calls). Projects still on React 18 should skip this section.

The core principles can be summarized in four sentences (from the skill’s README): Composition over configuration; lift state up; internal child components read from Context; use explicit names for variants.

Installation and Activation¶

This skill follows the Agent Skills format and can be installed via Vercel’s skills CLI. The CLI supports agents including Cursor, Claude Code, Codex, and OpenCode.

To install only the composition-patterns skill (consistent with the skills.sh page):

npx skills add https://github.com/vercel-labs/agent-skills --skill composition-patterns

Or use the repository shorthand followed by the skill name:

npx skills add vercel-labs/agent-skills --skill composition-patterns

To install the entire agent-skills collection:

npx skills add vercel-labs/agent-skills

Common options (from the vercel-labs/skills CLI documentation):
- Installs to the project’s Agent skills directory by default for team sharing
- -g: Install to the user’s global directory
- -a claude-code / -a cursor: Specify the target agent
- -y: Skip confirmation, suitable for CI environments

After installation, the agent will automatically reference the skill when it detects relevant tasks; you can also explicitly request “Refactor this component using the composition-patterns” in a conversation.

The general directory structure is as follows:
- SKILL.md: General instructions and rule index for agents
- rules/*.md: Individual rules with incorrect/correct examples
- AGENTS.md: Compilation document for all rules
- metadata.json: Version and summary (current version is 1.0.0, dated January 2026)

Typical Usage Examples¶

1. Ask the Agent to Refactor According to the Rules¶

After installation, you can prompt like this (aligned with the official “When to Apply” guidelines):

Please refactor this Composer using the composition-patterns: remove boolean props like isThread / isEditing,
and replace them with compound components and explicit variants (ChannelComposer / ThreadComposer / EditComposer).

The agent should read files like rules/architecture-avoid-boolean-props.md instead of modifying code based on vague impressions.

2. Boolean Props → Composite Variants (simplified official example)¶

Incorrect approach: A giant Composer relying on boolean branches:

function Composer({
  onSubmit,
  isThread,
  channelId,
  isDMThread,
  dmId,
  isEditing,
  isForwarding,
}: Props) {
  return (
    <form>
      <Header />
      <Input />
      {isDMThread ? (
        <AlsoSendToDMField id={dmId} />
      ) : isThread ? (
        <AlsoSendToChannelField id={channelId} />
      ) : null}
      {isEditing ? <EditActions /> : isForwarding ? <ForwardActions /> : <DefaultActions />}
      <Footer onSubmit={onSubmit} />
    </form>
  )
}

Correct approach: Variants combine shared internal components individually:

function ThreadComposer({ channelId }: { channelId: string }) {
  return (
    <Composer.Frame>
      <Composer.Header />
      <Composer.Input />
      <AlsoSendToChannelField id={channelId} />
      <Composer.Footer>
        <Composer.Formatting />
        <Composer.Emojis />
        <Composer.Submit />
      </Composer.Footer>
    </Composer.Frame>
  )
}

3. Compound Components + Context Interface¶

The official recommendation is to export a composite object, and inject state / actions / meta via the Provider:

const Composer = {
  Provider: ComposerProvider,
  Frame: ComposerFrame,
  Input: ComposerInput,
  Submit: ComposerSubmit,
  Header: ComposerHeader,
  Footer: ComposerFooter,
}

// Usage
<Composer.Provider state={state} actions={actions} meta={meta}>
  <Composer.Frame>
    <Composer.Header />
    <Composer.Input />
    <Composer.Footer>
      <Composer.Formatting />
      <Composer.Submit />
    </Composer.Footer>
  </Composer.Frame>
</Composer.Provider>

The same Composer.Input can be attached to a local form Provider or a channel synchronization Provider, because the UI only depends on the interface, not the specific state implementation.

4. React 19 Syntax (19+ only)¶

// ref as a regular prop, no need for forwardRef
function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
  return <TextInput ref={ref} {...props} />
}

// Use use() to read Context
const value = use(MyContext)

When you need a single detailed rule, you can directly open the corresponding rule file, for example:

rules/architecture-avoid-boolean-props.md
rules/state-context-interface.md
rules/react19-no-forwardref.md

Applicable Scenarios and Notes¶

Suitable for:
- React component libraries, design systems, complex form UIs like chat/editors
- Teams using agents like Cursor, Claude Code, or Codex for refactoring or code reviews
- Wanting AI to generate code that follows a unified architecture instead of piling on props

Notes:
1. This is an architectural/composition pattern skill, not a performance-focused one (for performance, see react-best-practices in the same repository). The official materials do not treat “server/client boundary” as a topic for this skill.
2. The React 19 section has version requirements; React 18 projects should ignore react19-* rules.
3. Most examples in the rules lean toward compound components and Context; if a component is extremely simple, there is no need to forcefully split it just to “follow the pattern”.
4. Refer to the in-repository SKILL.md / rules/ / AGENTS.md as the authoritative source; agents should read the rule files before modifying code, avoiding relying only on summaries.

Summary¶

The composition-patterns skill translates principles like “stop adding boolean toggles, use composition to express variants, move state to Providers, and let UIs only recognize interfaces” into a rule set executable by AI agents. For both humans and AI, the value lies in ensuring that as components grow, their behavior remains predictable, reusable, and interchangeable in implementation.

Official links:
- GitHub: https://github.com/vercel-labs/agent-skills/tree/main/skills/composition-patterns
- skills.sh: https://skills.sh/vercel-labs/agent-skills/composition-patterns