Add Vercel React best practices skill with 45 optimization rules

[cseagraves]

Summary

This PR adds a comprehensive React and Next.js performance optimization skill to the agent system. The skill contains 45 rules across 8 categories, organized by impact level and designed to guide automated code refactoring and generation.

Key Changes

• Added SKILL.md: Main skill definition with overview of all 45 rules organized into 8 priority categories:

  • Eliminating Waterfalls (CRITICAL) - async patterns
  • Bundle Size Optimization (CRITICAL) - import and code-splitting strategies
  • Server-Side Performance (HIGH) - caching and data fetching
  • Client-Side Data Fetching (MEDIUM-HIGH) - deduplication and SWR
  • Re-render Optimization (MEDIUM) - memoization and state management
  • Rendering Performance (MEDIUM) - CSS and DOM optimization
  • JavaScript Performance (LOW-MEDIUM) - algorithmic improvements
  • Advanced Patterns (LOW) - refs and hooks

• Added 45 individual rule files in rules/ directory, each containing:

  • Clear explanation of why the optimization matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references where applicable

• Added AGENTS.md: Compiled full guide with all rules expanded for comprehensive reference

Notable Implementation Details

• Rules are prefixed by category (e.g., async-, bundle-, server-) for easy identification
• Each rule includes impact level and tags for filtering and discovery
• Rules progress from critical performance wins (2-10× improvements) to lower-impact optimizations
• Practical examples use real-world scenarios (Monaco editor, message lists, API routes)
• Includes modern JavaScript features (.toSorted(), Promise.all(), dynamic imports)
• References external resources (better-all, SWR, Next.js docs) for deeper learning
• Covers both React and Next.js specific patterns (Server Components, API routes, dynamic imports)

Use Cases

This skill enables:

• Automated code review and refactoring suggestions
• Performance-focused code generation
• Developer education on React/Next.js best practices
• Consistent optimization patterns across codebases

https://claude.ai/code/session_015fSVBtppffeJSuTcWD3U3Z

[vercel]

@claude is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

This PR introduces a new “Vercel React best practices” skill (with multiple rule files) and expands the repo’s Claude Code documentation/command ecosystem with additional guides, commands, and agent definitions.

Changes:

• Added a Vercel-oriented React/Next.js performance optimization skill with multiple rule documents.
• Added numerous Claude Code slash commands and agent definitions to standardize workflows (review, deploy, Supabase, etc.).
• Added multiple documentation guides/audit outputs to improve project context and onboarding.

Reviewed changes

Copilot reviewed 109 out of 851 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
.claude/documents/guides-dec-2025/claude_code_context_engineering_concise_field_guide_dec_2025.md	Adds a concise field guide for context engineering patterns and file taxonomy.
.claude/commands/update-claude-md.md	Adds a workflow command doc for keeping CLAUDE.md files updated.
.claude/commands/supabase/writing-supabase-edge-functions.md	Adds Supabase Edge Function authoring guidance and templates.
.claude/commands/supabase/setup-supabase-auth.md	Adds a step-by-step Supabase Auth setup command guide for Next.js.
.claude/commands/supabase/postgres-sql-style-guide.md	Adds a PostgreSQL style guide for consistent SQL authoring.
.claude/commands/supabase/create-rls-policies.md	Adds an RLS policy-generation command doc with rules and examples.
.claude/commands/supabase/create-migration.md	Adds a migration creation guide with naming and SQL guidelines.
.claude/commands/supabase/create-db-functions.md	Adds a guide for authoring PostgreSQL functions with Supabase best practices.
.claude/commands/search-papers.md	Adds a command doc for paper search + citation integration.
.claude/commands/review/type-check.md	Adds a “type-check” workflow doc for TypeScript issue remediation.
.claude/commands/review/fix-vercel-build.md	Adds a workflow doc for diagnosing/fixing Vercel build failures.
.claude/commands/review/fix-react-hooks.md	Adds a workflow doc for React hooks dependency/loop issues.
.claude/commands/review/fix-citations.md	Adds a workflow doc for fixing citation feature issues.
.claude/commands/review/code_review_command.md	Adds an “expert code review” command template with focus areas and formatting.
.claude/commands/review-auth-middleware.md	Adds a command doc for auditing auth/middleware/Supabase client usage.
.claude/commands/review-app-icons.md	Adds a command doc for auditing/fixing PWA/app icon branding.
.claude/commands/pre-deploy.md	Adds a pre-deploy checklist command doc.
.claude/commands/performance_optimizer.md	Adds a performance analysis/optimization command doc with checklists and tools.
.claude/commands/git-push.md	Adds a “git push” workflow doc with commit message guidance.
.claude/commands/fullstack-architect.md	Adds a role prompt for architecture planning in this repo’s stack.
.claude/commands/create/create-feature.md	Adds a feature implementation workflow prompt with phases.
.claude/commands/codebase_context_proj.md	Adds a codebase context loader command with architecture references.
.claude/commands/begin.md	Adds a “Begin Session” command to inject orchestration guidance.
.claude/commands/ai/ai_tool_builder.md	Adds a tool development workflow doc for AI tool creation/integration.
.claude/commands/ai/ai_expert_context.md	Adds an “AI engineering expert mode” context prompt.
.claude/audit-app-documentation.md	Adds an audit report for app/ documentation coverage and validation.
.claude/ai-tools-expert.md	Adds an AI tools expert agent definition.
.claude/agents/ui-engineer.md	Adds a UI engineer agent definition.
.claude/agents/tailwind-expert.md	Adds a Tailwind specialist agent definition with repo constraints.
.claude/agents/supabase-expert.md	Adds a Supabase/Postgres/Drizzle specialist agent definition.
.claude/agents/senior-code-reviewer.md	Adds a senior code reviewer agent definition.
.claude/agents/security-expert.md	Adds a security specialist agent definition.
.claude/agents/research-search-expert.md	Adds a research/citation agent definition with source requirements.
.claude/agents/react-expert.md	Adds a React specialist agent definition with repo invariants.
.claude/agents/nextjs-16/nextjs-16-expert.md	Adds a Next.js 16 specialist agent definition.
.claude/agents/nextjs-16/nextjs-16-cache-expert.md	Adds a Next.js 16 caching specialist agent definition.
.claude/agents/docs-maintainer.md	Adds a docs maintainer agent definition with standards and process.
.claude/agents/api-route-architect.md	Adds an API route architect agent definition with security constraints.
.claude/agents/agent-expert.md	Adds an agent design specialist definition.
.claude/agent-rewrite-summary.md	Adds a summary doc describing agent rewrites and removed contamination.
.claude/QUICK_START_WEB.md	Adds quick-start documentation for Claude Code web environment setup.
.claude/ENV_SETUP_WEB.md	Adds environment variable setup documentation for Claude Code web.
.claude/DOCUMENTATION_CROSS_REFERENCES.md	Adds documentation cross-reference validation results.
.claude/AUDIT_SUMMARY.md	Adds an executive summary for the app/ documentation audit.
.agent/skills/web-design-guidelines/SKILL.md	Adds a skill definition for Web Interface Guidelines compliance reviews.
.agent/skills/vercel-react-best-practices/SKILL.md	Adds the top-level skill definition and index for Vercel React best practices.
.agent/skills/vercel-react-best-practices/rules/server-serialization.md	Adds a rule doc about minimizing RSC boundary serialization.
.agent/skills/vercel-react-best-practices/rules/server-parallel-fetching.md	Adds a rule doc about parallelizing RSC fetches via composition.
.agent/skills/vercel-react-best-practices/rules/server-cache-react.md	Adds a rule doc about per-request deduplication with React.cache().
.agent/skills/vercel-react-best-practices/rules/server-cache-lru.md	Adds a rule doc about cross-request LRU caching.
.agent/skills/vercel-react-best-practices/rules/server-after-nonblocking.md	Adds a rule doc about using Next.js after() for non-blocking work.
.agent/skills/vercel-react-best-practices/rules/client-swr-dedup.md	Adds a rule doc about SWR request deduplication.
.agent/skills/vercel-react-best-practices/rules/client-event-listeners.md	Adds a rule doc about deduplicating global event listeners.
.agent/skills/vercel-react-best-practices/rules/rerender-transitions.md	Adds a rule doc about startTransition for non-urgent updates.
.agent/skills/vercel-react-best-practices/rules/rerender-memo.md	Adds a rule doc about extracting work into memoized components.
.agent/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md	Adds a rule doc about lazy state initialization for expensive initial values.
.agent/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md	Adds a rule doc about functional setState to avoid stale closures.
.agent/skills/vercel-react-best-practices/rules/rerender-derived-state.md	Adds a rule doc about subscribing to derived booleans rather than continuous values.
.agent/skills/vercel-react-best-practices/rules/rerender-dependencies.md	Adds a rule doc about narrowing effect dependencies.
.agent/skills/vercel-react-best-practices/rules/rerender-defer-reads.md	Adds a rule doc about deferring state reads to the usage point.
.agent/skills/vercel-react-best-practices/rules/rendering-svg-precision.md	Adds a rule doc about reducing SVG coordinate precision.
.agent/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md	Adds a rule doc about avoiding hydration mismatch/flicker for client-only data.
.agent/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md	Adds a rule doc about hoisting static JSX.
.agent/skills/vercel-react-best-practices/rules/rendering-content-visibility.md	Adds a rule doc about using content-visibility for long lists.
.agent/skills/vercel-react-best-practices/rules/rendering-conditional-render.md	Adds a rule doc about ternary vs && for numeric/falsy conditions.
.agent/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md	Adds a rule doc about animating an SVG wrapper for better acceleration.
.agent/skills/vercel-react-best-practices/rules/rendering-activity.md	Adds a rule doc about using an Activity component to preserve state/DOM.
.agent/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md	Adds a rule doc about using toSorted() for immutability.
.agent/skills/vercel-react-best-practices/rules/js-set-map-lookups.md	Adds a rule doc about Set/Map for O(1) lookups.
.agent/skills/vercel-react-best-practices/rules/js-min-max-loop.md	Adds a rule doc about using a loop for min/max vs sorting.
.agent/skills/vercel-react-best-practices/rules/js-length-check-first.md	Adds a rule doc about early length checks before expensive array comparisons.
.agent/skills/vercel-react-best-practices/rules/js-index-maps.md	Adds a rule doc about building index maps for repeated lookups.
.agent/skills/vercel-react-best-practices/rules/js-hoist-regexp.md	Adds a rule doc about hoisting/memoizing RegExp creation.
.agent/skills/vercel-react-best-practices/rules/js-early-exit.md	Adds a rule doc about early returns to skip unnecessary processing.
.agent/skills/vercel-react-best-practices/rules/js-combine-iterations.md	Adds a rule doc about combining multiple iterations into one loop.
.agent/skills/vercel-react-best-practices/rules/js-cache-storage.md	Adds a rule doc about caching Storage API reads.
.agent/skills/vercel-react-best-practices/rules/js-cache-property-access.md	Adds a rule doc about caching property accesses in hot loops.
.agent/skills/vercel-react-best-practices/rules/js-cache-function-results.md	Adds a rule doc about caching repeated function computations.
.agent/skills/vercel-react-best-practices/rules/js-batch-dom-css.md	Adds a rule doc about batching DOM style updates.
.agent/skills/vercel-react-best-practices/rules/bundle-preload.md	Adds a rule doc about intent-based preloading.
.agent/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md	Adds a rule doc about next/dynamic for large components.
.agent/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md	Adds a rule doc about deferring third-party libs until after hydration.
.agent/skills/vercel-react-best-practices/rules/bundle-conditional.md	Adds a rule doc about conditional module/data loading.
.agent/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md	Adds a rule doc about avoiding barrel imports/using optimizePackageImports.
.agent/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md	Adds a rule doc about strategic Suspense boundaries for streaming.
.agent/skills/vercel-react-best-practices/rules/async-parallel.md	Adds a rule doc about Promise.all for parallelizing independent async work.
.agent/skills/vercel-react-best-practices/rules/async-dependencies.md	Adds a rule doc about dependency-based parallelization with better-all.
.agent/skills/vercel-react-best-practices/rules/async-defer-await.md	Adds a rule doc about deferring awaits until needed.
.agent/skills/vercel-react-best-practices/rules/async-api-routes.md	Adds a rule doc about avoiding waterfalls in API routes/server actions.
.agent/skills/vercel-react-best-practices/rules/advanced-use-latest.md	Adds a rule doc about a useLatest ref pattern for stable callbacks.
.agent/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md	Adds a rule doc about storing event handlers in refs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Typo: 'dependecnies' should be 'dependencies'.

Suggested change

	3. Do NOT use bare specifiers when importing dependecnies. If you need to use an external dependency, make sure it's prefixed with either `npm:` or `jsr:`. For example, `@supabase/supabase-js` should be written as `npm:@supabase/supabase-js`.
	3. Do NOT use bare specifiers when importing dependencies. If you need to use an external dependency, make sure it's prefixed with either `npm:` or `jsr:`. For example, `@supabase/supabase-js` should be written as `npm:@supabase/supabase-js`.

[Copilot]

There are a couple of formatting/accuracy issues here: (1) the stray @ before deno.land/x and unpkg.com is confusing, and (2) the Node import process... example is missing a closing backtick and quote, which makes the example invalid. Clean up the inline code formatting so readers can copy/paste the import.

Suggested change

	5. For external dependencies, importing via `npm:` and `jsr:` is preferred. Minimize the use of imports from @`deno.land/x` , `esm.sh` and @`unpkg.com` . If you have a package from one of those CDNs, you can replace the CDN hostname with `npm:` specifier.
	6. You can also use Node built-in APIs. You will need to import them using `node:` specifier. For example, to import Node process: `import process from "node:process". Use Node APIs when you find gaps in Deno APIs.
	5. For external dependencies, importing via `npm:` and `jsr:` is preferred. Minimize the use of imports from `deno.land/x`, `esm.sh` and `unpkg.com`. If you have a package from one of those CDNs, you can replace the CDN hostname with `npm:` specifier.
	6. You can also use Node built-in APIs. You will need to import them using `node:` specifier. For example, to import Node process: `import process from "node:process"`. Use Node APIs when you find gaps in Deno APIs.

[Copilot]

The verification curl uses /auth/signup, but earlier the generated route is consistently documented as /auth/sign-up (with a hyphen). This will cause the verification step to fail for readers following the rest of the guide. Update the curl example to the correct route.

Suggested change

	curl -I http://localhost:3000/auth/signup
	curl -I http://localhost:3000/auth/sign-up

[Copilot]

Grammar: 'MUST following' should be 'MUST follow'.

Suggested change

	The file MUST following this naming convention:
	The file MUST follow this naming convention:

[Copilot]

This example SQL is not valid Postgres RLS syntax and also contradicts the rules stated above in the same document: INSERT policies should use WITH CHECK (not WITH) and should not include USING. Update the sample to valid Postgres syntax and make it consistent with the earlier policy rules.

Suggested change

	CREATE POLICY "My descriptive policy." ON books FOR INSERT to authenticated USING ( (select auth.uid()) = author_id ) WITH ( true );
	CREATE POLICY "My descriptive policy." ON books
	FOR INSERT TO authenticated
	WITH CHECK ( auth.uid() = author_id );

[Copilot]

This conflicts with other added docs that state the repo uses Biome (and not ESLint). If ESLint is not actually part of the toolchain, this instruction will mislead and waste time. Align the pre-deploy doc with the repo’s real lint/format tooling (e.g., Biome-only), or explicitly document when both are expected.

[Copilot]

This agent description references 'AI SDK 6' and an 'ai-sdk-6-migration', while multiple other docs added in this PR reference AI SDK 5 patterns. This mismatch will cause incorrect guidance when the agent is invoked. Update the agent to match the actual AI SDK major version and migration workflow used in this repo, or clearly mark it as version-specific/experimental.

Suggested change

	description: Use when implementing or modifying Orbis chat tools (AI SDK 6 tool() + factory pattern), tool registration in app/(chat)/api/chat/route.ts, dataStream UI events, or tool display components. Focuses on tool logic, external APIs (FRED/Perplexity), and unified UI display components. Not for route-level pipeline fixes (use ai-sdk-6-migration).
	description: Use when implementing or modifying Orbis chat tools (AI SDK 5 tool() + factory pattern), tool registration in app/(chat)/api/chat/route.ts, dataStream UI events, or tool display components. Focuses on tool logic, external APIs (FRED/Perplexity), and unified UI display components. Not for route-level pipeline fixes (use ai-sdk-5-migration).

[Copilot]

The example uses Activity from react, which is not a commonly available/stable React API and may not exist in many React/Next.js setups, making the rule’s example fail to compile for consumers. Consider replacing this with a broadly supported pattern (e.g., keep the component mounted and toggle hidden/CSS visibility, or explicitly label it as React experimental and provide an alternative).

[Copilot]

This skill rule is positioned as generally applicable guidance, but it references a project-local helper (@/lib/swr) that likely won’t exist in other repos. Prefer documenting canonical SWR usage (e.g., useSWRImmutable from swr/immutable, or useSWR with immutable config) so the rule is portable and unambiguous.

Suggested change

	import { useImmutableSWR } from '@/lib/swr'
	function StaticContent() {
	const { data } = useImmutableSWR('/api/config', fetcher)
	import useSWRImmutable from 'swr/immutable'
	function StaticContent() {
	const { data } = useSWRImmutable('/api/config', fetcher)

[Copilot]

Inside the after(async () => { ... }) callback, logUserAction(...) is called without await/return/void. If it returns a promise, this can create an unhandled rejection and makes failure handling unclear. Either await logUserAction(...) (and handle errors) or explicitly void logUserAction(...).catch(...) to make the intention clear.

Suggested change

	logUserAction({ sessionCookie, userAgent })
	try {
	await logUserAction({ sessionCookie, userAgent })
	} catch (error) {
	console.error('Failed to log user action', error)
	}

[vercel]

Additional Suggestion:

Next.js middleware file named proxy.ts instead of middleware.ts, so MCP query parameter authentication never executes

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 25e362651a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop returning decrypted API keys to the client

AGENTS.md (repo root) explicitly says “Never expose these … to the client: … Any user‑provided API keys.” This handler now decrypts stored keys and returns the plaintext value in the JSON response, which pushes secrets into the browser (and makes them accessible to XSS, extensions, or leaked sessions). Consider returning only metadata (provider/createdAt) or a masked indicator, and only showing full keys at creation time.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove dynamic values from sub-agent log messages

AGENTS.md (repo root) requires “All log statements MUST use static strings only.” This log entry embeds ${name} and ${description} directly into user-facing task logs, which can include repo names, file paths, or other sensitive context. Use a static message (e.g., “Sub-agent started”) and store the dynamic details in non-log fields if needed.

Useful? React with 👍 / 👎.