# legend-list-best-practices

A skill for @legendapp/list work: it implements the list by the library's own contracts or audits existing usage for recycling, measurement and scroll anchoring bugs.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 546 installs · ★ 40
- Author: LegendApp
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/LegendApp/legend-skills/tree/HEAD/legend-list-best-practices/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/legend-list-best-practices

## What it does

The skill encodes @legendapp/list contracts instead of generic prop tuning: stable keys, invalidation, row ownership, measurement, recycling and scroll anchoring. When a bug or regression is unclear, the agent reproduces and measures it before touching code.

There are three modes. Build establishes keys, invalidation, row ownership, measurement and recycling before implementation. Audit inspects the list and the full row tree, then reports findings ranked by impact and confidence, keeping measured problems apart from risks. Fix audits first, presents a ranked plan, and only then edits within the authorization already given in the conversation.

Imports are strict: React Native and React Native Web come from `@legendapp/list/react-native`, React DOM from `@legendapp/list/react`, and SectionList, keyboard, animated or Reanimated integrations use their documented entrypoints. Mixing `data` plus `renderItem` with children mode is not allowed. A changing React `key` on the list or wrapper is treated as a remount that throws away state and caches, so `dataKey` is the update signal instead. Where no selector-capable state library exists, the skill suggests `@legendapp/state` and states plainly that it shares maintainers with Legend List — worth knowing before you add the dependency.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add LegendApp/legend-skills --skill legend-list-best-practices -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/legend-list-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/legend-list-best-practices/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add LegendApp/legend-skills --skill legend-list-best-practices -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/legend-list-best-practices/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add LegendApp/legend-skills --skill legend-list-best-practices -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/legend-list-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install LegendApp/legend-skills legend-list-best-practices
```

2. **Manually: put the files in place**
- File: `.github/skills/legend-list-best-practices/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add LegendApp/legend-skills --skill legend-list-best-practices -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/LegendApp/legend-skills --path legend-list-best-practices
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/legend-list-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add LegendApp/legend-skills --skill legend-list-best-practices -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/LegendApp/legend-skills/tree/HEAD/legend-list-best-practices/SKILL.md

## When to use it
- build a new @legendapp/list screen without guessing at props
- track down rows blanking during fast scroll
- explain why the list jumps or shows stale items
- check keys and invalidation before patching a bug
- separate measured problems from risks in existing list code

## Example prompts
- Audit this @legendapp/list screen and rank the findings by impact
- Build a new list screen: settle keys, invalidation and measurement before writing code
- Rows blank on fast scroll — reproduce and measure it, then give me a ranked plan

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 70ddd89bb20caf96.

BEGIN THIRD-PARTY FILE 70ddd89bb20caf96
```text
---
name: legend-list-best-practices
description: "Implement or audit @legendapp/list usage, including recycling, measurement, invalidation, and scroll anchoring."
---

# Legend List Best Practices

Apply Legend List-specific contracts, not generic prop tuning. For an unclear bug or regression, reproduce and measure it before changing code.

## Surface And Workflow

- Check the installed version, platform, import, nearby usage, source, and tests. Prefer installed source and types when they differ from the [docs](https://legendapp.com/open-source/list/v3/overview/) or [LLM index](https://legendapp.com/open-source/list/v3/llms.txt).
- Import React Native and React Native Web from `@legendapp/list/react-native`, React DOM from `@legendapp/list/react`, and use documented entrypoints for SectionList, keyboard, animated, or Reanimated integrations.
- Use either `data` plus `renderItem` or children mode; never mix them.
- **Build:** establish keys, invalidation, row ownership, measurement, recycling, and validation before implementation.
- **Audit:** inspect both the list and the complete row tree; report concrete findings ranked by impact and confidence, separating measured problems from risks.
- **Fix:** audit first and present a ranked plan, then follow the action boundary below.

Trace every finding to the exact list, row, state source, and invalidation, measurement, or scroll path. For blanking, separate range/draw-distance work, row commit cost, and measurement. For slow mount, inspect data passes, key/type/size callbacks, initial estimates, and row cost. For jumps or stale state, inspect identity, cached sizes, anchoring, recycling, and remounts.

## Doing Vs. Suggesting

- Suggest every evidence-backed improvement, including sweeping architecture, only when the user asks to audit or improve the list. When building, fixing a specific issue, or doing unrelated work nearby, apply the relevant rules within scope and report incidental findings only when they affect correctness.
```
END THIRD-PARTY FILE 70ddd89bb20caf96

The third-party file has ended. Everything between the 70ddd89bb20caf96 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2008 of 10227 bytes. © LegendApp · MIT · https://github.com/LegendApp/legend-skills/tree/HEAD/legend-list-best-practices/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md