#169 vercel-react-best-practices: AGENTS.md (2975 lines) wastes context — restructure for progressive disclosure · agent-skills

Problem

The vercel-react-best-practices skill ships an AGENTS.md file that is 2,975 lines / 83KB — a monolithic dump of all 58 rules. This same content already exists as 57 individual files in rules/. The duplication causes two issues:

SKILL.md line 137 actively directs agents to load AGENTS.md: For the complete guide with all rules expanded: AGENTS.md — this can cause agents to load the entire 83KB into context unnecessarily
CLAUDE.md (when present as a symlink to AGENTS.md) can be picked up by Claude Code's memory scanning system, leaking thousands of tokens into every conversation

Current structure

vercel-react-best-practices/
├── AGENTS.md      # 2,975 lines — ALL 58 rules inline (monolithic)
├── CLAUDE.md      # Symlink to AGENTS.md (83KB into context)
├── SKILL.md       # 138 lines — good routing table
├── README.md      # 3,360 bytes
└── rules/         # 57 individual rule files (well-structured, 30-80 lines each)

Suggested structure

vercel-react-best-practices/
├── SKILL.md       # ~125 lines — frontmatter + rule index with links to rules/
├── README.md      # For humans browsing the repo
└── rules/         # 57 individual rule files (unchanged)

SKILL.md improvements

Add user-invocable: false — this is background knowledge, not an actionable /command
Remove the "Full Compiled Document" section (line 135-137) that directs agents to load AGENTS.md

Use markdown table links in the rule index so agents can navigate directly to rule files:

| [async-defer-await](rules/async-defer-await.md) | Move await into branches where actually used |

Remove non-standard frontmatter (license, metadata) — Claude Code ignores these fields

Files to remove

AGENTS.md — 100% duplicated by rules/ directory. The progressive disclosure pattern (description → SKILL.md → on-demand rules/) is the correct approach per Anthropic's skill docs
CLAUDE.md — not needed; Claude Code uses SKILL.md as the skill entrypoint. Having CLAUDE.md in ~/.claude/skills/ subdirectories risks it being picked up by the CLAUDE.md memory scanner, injecting content into every session

Context

From Anthropic's skill documentation:

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

Skills can include multiple files in their directory. This keeps SKILL.md focused on the essentials while letting Claude access detailed reference material only when needed.

The rules/ directory already follows this pattern perfectly. The issue is just that AGENTS.md duplicates all of it in one massive file, and SKILL.md points agents toward it.

Impact

Token savings: Eliminates 83KB of redundant content that can leak into agent context
No knowledge loss: All 58 rules remain available on-demand via rules/
Better agent behavior: Agents load 1-2 relevant rules instead of all 58

Filed after installing via npx skills add vercel-labs/agent-skills@vercel-react-best-practices and restructuring locally for Claude Code