The vercel-composition-patterns skill, reviewed

What it tells the agent to do

1. Apply when refactoring boolean-heavy components, building libraries, designing APIs or reviewing architecture
2. Work through the rule categories by priority, starting with Component Architecture (HIGH)
3. Use the one-line quick-reference rules to guide changes, such as composition over boolean props and state lifted into providers
4. Skip the React 19 section if the project uses React 18 or earlier
5. Open rules/<rule-name>.md for the explanation and incorrect/correct code examples
6. Read AGENTS.md for the full guide with all rules expanded

Lines worth reading

Straight from the file, with why each one matters.

1. line 4Use when refactoring components with

   The description names real symptoms (boolean prop proliferation) and pattern names, so it matches the words people actually type.

2. line 45Don't add boolean props to customize

   The core thesis in one line, ranked HIGH. Every isPrimary, isCompact or hasIcon prop is a vote for this skill.

3. line 52Provider is the only place that knows how

   A sharp rule. Consumers get an interface and never see the state mechanics. It is dependency injection, React-style.

4. line 69Don't use `forwardRef`; use `use()` instead of `useContext()`

   Two unrelated React 19 changes share one line, and the line never says what replaces forwardRef (ref as a plain prop).

5. line 19These patterns make codebases easier for both humans and AI

   A pitch aimed partly at the reader's agent: composition is sold as AI-friendly architecture.

Watch out for

Nothing risky that Kin could see in SKILL.md. Scripts beside it were not read.

The scorecard

• TriggerSays when to use it
  8/10

  Clear uses and request words in the description; leads with a slogan, not the task.

• FocusOne clear job
  8/10

  One job: React component API design. The React 19 rule is a small side trip.

• LeanLight to load
  9/10

  About 65 lines, a priority table and links out. Ideal progressive disclosure.

• ConcreteSteps you can follow
  4/10

  No code at all in SKILL.md. Examples are in rule files that could not be listed.

• SafeSafe to run
  10/10

  Pure guidance: no commands, network calls or secrets.

How it could be better

1. Split and complete the React 19 rule

   Line 69 bundles two changes and never says what replaces forwardRef, so the agent may delete it without passing ref.

   Add

   - `react19-no-forwardref` - In React 19, accept `ref` as a regular prop instead of wrapping components in `forwardRef`; read context with `use(Context)` instead of `useContext(Context)`

   Copy

2. Inline one before/after example

   If the rules/ folder is missing, the agent has only slogans. One short example anchors the main rule.

   Add

   ### Example: boolean props → composition
   
   ```tsx
   // Before
   <Composer isThread isEditing hasAttachments />
   // After
   <Composer.Provider>
     <Composer.Input />
     <Composer.Attachments />
   </Composer.Provider>
   ```
   <adjust names to match rules/architecture-avoid-boolean-props.md>

   Copy

3. Say what done looks like

   There is no check for a finished refactor, so the agent cannot verify its work.

   Add

   ## Done when
   
   - No component takes boolean props that switch layout or behavior
   - Variants are separate components that compose shared internals
   - State lives in one provider; consumers use only its state/actions/meta interface

   Copy

4. List every rule file path

   Only two of eight rule files are shown, so the agent must guess the other paths from the prefixes.

   Add

   Rule files (open only the ones relevant to the task):
   - rules/architecture-avoid-boolean-props.md
   - rules/architecture-compound-components.md
   - rules/<rule-name>.md for each remaining rule above

   Copy