# Understanding the narrow-react-prop-types Skill: Automating TypeScript Prop Narrowing for React Components

> Automate TypeScript prop narrowing for React with the narrow-react-prop-types skill. Analyze production usage to refine component APIs and eliminate impossible states.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: deep-dive
- Published: 2026-09-12

---

**The narrow-react-prop-types skill automatically tightens TypeScript prop interfaces for React components by analyzing live production usage and removing impossible states from the component API.**

The narrow-react-prop-types skill in the humanlayer/skills repository eliminates defensive coding overhead by transforming broad, test-optimized React prop types into strict contracts that match real runtime behavior. By analyzing actual import patterns across production codebases, this automation reduces TypeScript complexity while improving type safety throughout the repository.

## What is the narrow-react-prop-types Skill?

The narrow-react-prop-types skill is a specialized automation that refines React component prop interfaces to accurately reflect production usage rather than test or Storybook scenarios. According to the specification in [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md), the skill targets components whose prop interfaces have been deliberately broadened with optional fields for testing convenience.

When applied, the skill rewrites exported prop types to exclude impossible states, preferring derived TypeScript utility types such as `Parameters<typeof fn>[0]` or `ReturnType<typeof fn]` where appropriate. The result is a component public API that requires less defensive logic and provides stronger compile-time guarantees.

## Core Workflow and Implementation

The skill executes a seven-phase workflow to safely narrow component props without breaking production code.

### Detection Phase

The skill first identifies suspect components exhibiting characteristics of artificially broadened interfaces. These patterns include interfaces with excessive optional fields or optional callbacks that may never be invoked in production code.

### Collection and Analysis

Next, the skill scans the entire codebase to collect every live import and usage instance of the target component. It rigorously separates production usage from support code, including tests, Storybook stories, and mock implementations, ensuring that only runtime-valid usage patterns inform the new type definition.

### Derivation and Rewriting

Based on the collected call sites, the skill derives the true required, optional, or obsolete status of each prop. It then rewrites the exported prop type to be as strict as possible, eliminating fields that are never provided in production and converting optional props to required when every live usage supplies them.

### Propagation and Validation

The skill propagates the narrowed contract to any child components that inherit the broad type, ensuring consistency across the component tree. It then updates supporting code—stories, tests, and mocks—to comply with the new strict contract. Finally, it validates the changes through package-level type-checking and quality checks as specified in [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md).

## Practical Examples

### CI Integration

The skill integrates into continuous integration pipelines through GitHub Actions. The reference implementation in [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml) demonstrates how to invoke the skill after ensuring the package builds correctly:

```bash

# Ensure the package builds first

bun run typecheck --filter <package>

# The skill is then invoked by the GitHub Action defined in the agent-narrow-component-props.yml reference

```

### Interface Transformation

Consider a button component with artificially loosened types for testing flexibility. The skill transforms the interface based on actual usage:

```ts
// Before narrowing
export interface MyButtonProps {
  label?: string;
  onClick?: () => void;
}

// After applying the skill (derived from live usage)
export interface MyButtonProps {
  label: string;                         // always supplied by live code
  onClick: () => void;                   // made required because every live call provides it
}

```

### Storybook Updates

When the skill narrows prop types, it automatically updates Storybook stories to satisfy the new contract. In [`stories/MyButton.stories.tsx`](https://github.com/humanlayer/skills/blob/main/stories/MyButton.stories.tsx), the story must provide previously optional props that are now required:

```tsx
export const Default = () => (
  <MyButton
    label="Click me"
    onClick={() => console.log('clicked')}   // required after narrowing
  />
);

```

## Key Files and Architecture

The narrow-react-prop-types skill relies on several structured files within the humanlayer/skills repository:

- **[`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md)** — The authoritative specification documenting requirements, workflow phases, and validation checklists.
- **[`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml)** — Example GitHub Actions workflow demonstrating CI integration patterns.
- **[`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/response-template.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/response-template.md)** — Template for the automated PR body generated after processing components.
- **[`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/narrow-component-props-memory.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/narrow-component-props-memory.md)** — Sample memory file used by the skill's agent to retain state between execution runs.

## Summary

- The narrow-react-prop-types skill automates the transformation of broad React prop types into strict production-aligned contracts.
- It detects artificially broadened interfaces by analyzing optional fields and callback patterns.
- The seven-phase workflow includes detection, collection, derivation, rewriting, propagation, test updates, and validation.
- Key files reside in `plugins/narrow-react-prop-types/skills/narrow-react-prop-types/`, including [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) for specifications and [`agent-narrow-component-props.yml`](https://github.com/humanlayer/skills/blob/main/agent-narrow-component-props.yml) for CI integration examples.
- The skill improves type safety by eliminating impossible states and reducing defensive logic requirements in React components.

## Frequently Asked Questions

### How does the narrow-react-prop-types skill distinguish between production and test code?

The skill rigorously categorizes every import and usage instance of a component, separating production code from support files including tests, Storybook stories, and mocks. Only live production call sites influence the derived prop types, ensuring that test-only convenience props do not weaken the production API contract.

### What happens to existing tests and stories when props are narrowed?

The skill automatically updates supporting code—including Storybook stories and unit tests—to comply with the new stricter prop contracts. For example, it ensures that stories previously omitting required props now supply valid values, maintaining codebase integrity while enforcing stricter types.

### Can the narrow-react-prop-types skill handle derived TypeScript types?

Yes, the skill prefers derived types such as `Parameters<typeof fn>[0]` and `ReturnType<typeof fn]` when these accurately represent the component's usage patterns. This approach creates more maintainable type definitions that stay synchronized with actual implementation details rather than manual interface declarations.

### Where is the narrow-react-prop-types skill configured in the repository?

The primary specification resides in [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md), while CI integration examples are found in [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/references/agent-narrow-component-props.yml). The skill also utilizes memory files like [`narrow-component-props-memory.md`](https://github.com/humanlayer/skills/blob/main/narrow-component-props-memory.md) to maintain state across execution runs.