先日、というか今日、VercelがReactとNext.jsの最適化ノウハウを詰め込んだAgent Skillsを公開した。10年以上の本番運用で培った知見が45のルールにまとまっているらしい。

これは入れるしかない。

そもそもAgent Skillsって何？

Agent Skillsは、AIコーディングエージェント（Claude Code、Cursor、Codexなど）に特定の知識やワークフローを追加できる仕組みだ。スキルをインストールすると、エージェントがコードを書いたりレビューしたりする際に、そのスキルの知識を参照してくれる。

例えば「このコンポーネントを最適化して」と頼むと、スキルに書かれたベストプラクティスに基づいて具体的な改善案を出してくれる。

最近だとPlaywright MCPの代替となりうるagent-browserが公開されたことが記憶に新しい。MCPサーバーとしてではなくCLIコマンドとして動作し、Claude CodeなどのAIエージェントからはSkillsファイルを通じて必要に応じて呼び出す仕組みになっている。
MCPよりもこうしたSkillsベースのアプローチが今後スタンダードになっていく気がする。

インストールしてみる

インストールはびっくりするほど簡単だった。

npx add-skill vercel-labs/agent-skills

これだけ。実行すると対話形式でセットアップが始まる。

┌   add-skill
│
◇  Source: https://github.com/vercel-labs/agent-skills.git
│
◇  Repository cloned
│
◇  Found 2 skills
│
◇  Select skills to install
│  vercel-react-best-practices, web-design-guidelines

面白いのは、マシンにインストールされているAIエージェントを自動検出してくれるところ。自分の環境では5つ検出された。
curlでgithubから.claude/skills/vercel-react-best-practicesにスキル用のフォルダを作ってクローンする派の自分からしたらあまりにも楽で全部これになって欲しいと思った本当に。

◇  Detected 5 agents
│
◇  Select agents to install skills to
│  OpenCode, Claude Code, Codex, Cursor, VSCode

全部選択すると、各エージェントのスキルディレクトリに一括でインストールしてくれる。
デフォルトで全部選択になっているのでもし嫌だなーとなったら外そう。

◆  Successfully installed 10 skills
│
│    ✓ vercel-react-best-practices → Claude Code
│      ~/.claude/skills/vercel-react-best-practices
│
│    ✓ web-design-guidelines → Claude Code
│      ~/.claude/skills/web-design-guidelines

1コマンドで5つのエージェント × 2つのスキル = 10件のインストールが完了。便利。

vercel-react-best-practicesの中身

せっかくなので中身を見てみよう。このスキルはReactとNext.jsのパフォーマンス最適化に特化している。

8カテゴリ、45ルール

ルールは影響度順に8つのカテゴリに分類されている。

優先度	カテゴリ	影響度
1	ウォーターフォール排除	CRITICAL
2	バンドルサイズ最適化	CRITICAL
3	サーバーサイド性能	HIGH
4	クライアントサイドフェッチ	MEDIUM-HIGH
5	再レンダリング最適化	MEDIUM
6	レンダリング性能	MEDIUM
7	JavaScript性能	LOW-MEDIUM
8	高度なパターン	LOW

優先度1と2がCRITICALになっているのが興味深い。Vercelの公式ブログにはこう書かれている。

If a request waterfall adds 600ms of waiting time, it doesn't matter how optimized your useMemo calls are.

ウォーターフォールで600ms遅れているなら、useMemoをいくら最適化しても意味がない。まずは影響の大きいところから潰していくという考え方だ。

具体例：ウォーターフォールの排除

公式ブログに載っていた例がわかりやすかったので紹介する。

悪い例：

async function handleRequest(userId: string, skipProcessing: boolean) {
  const userData = await fetchUserData(userId)

  if (skipProcessing) {
    // skipProcessingがtrueでも、上でuserDataを待ってしまっている
    return { skipped: true }
  }

  return processUserData(userData)
}

良い例：

async function handleRequest(userId: string, skipProcessing: boolean) {
  if (skipProcessing) {
    return { skipped: true }
  }

  // 必要なときだけフェッチする
  const userData = await fetchUserData(userId)
  return processUserData(userData)
}

早期リターンを先に書くだけで、不要なAPIコールを減らせる。こういう「知っていれば簡単だけど、見落としがち」なパターンが45個まとまっている。
生成AIに初めから完璧なコードを書かせようとするよりも、作ったコードを修正するツールを発展させていく考えは正直最高だと思う。大好き。

web-design-guidelinesの中身

もう一つのスキルはUIデザインのガイドラインだ。こちらはVercel Design Teamが作成したもので、数百の設計判断がまとまっている。

主要なカテゴリ

カテゴリごとにいくつかピックアップしてみる。

Interactions

キーボード操作は全ての機能で使えるようにする（WAI-ARIA準拠）
ヒットターゲットの最小サイズはモバイルで44px
楽観的更新（Optimistic updates）でUXを向上させる
URLで状態管理する（共有・リロード・戻る/進むが壊れない）

Animations

prefers-reduced-motion対応は必須
GPU加速プロパティ（transform, opacity）を優先
transition: allは禁止（意図しないプロパティがアニメーションする）

Forms

Enterキーで送信できるようにする
送信ボタンは常に有効にしておく（送信中のみ無効化）
エラーは該当フィールドの近くに表示し、送信時は最初のエラーにフォーカス

Performance

React ScanやDevToolsで再レンダリングを追跡する
大きなリストは仮想化する（virtuaなど）
プリロードはabove-the-foldのみ

個人的に刺さったルール

Links are links. Use <a> or <Link> for navigation so standard browser behaviors work (Cmd/Ctrl+Click, middle-click, right-click to open in a new tab). Never substitute with <button> or <div> for navigational links.

リンクはリンクとして実装する。<button>や<div>で代用すると、Cmd+クリックで新しいタブで開く、といった標準的なブラウザの挙動が壊れる。

特に生成AIで実装したコードはたまーーーに、本当に稀にありがちなのでとても助かる。

CLAUDE.mdのベストプラクティス

スキルを入れたついでに、Claude CodeのCLAUDE.mdも見直してみた。いくつかの記事を参考にして、自分なりに腑に落ちた内容をまとめてみる。

簡潔に保つ

どうやらLLMは150〜200程度の指示しか確実に従えないらしい。Claude Codeのシステムプロンプトだけで50程度の指示が含まれているので、ユーザースコープのCLAUDE.mdには本当に必要なものだけを書くのがよさそうだ。

CLAUDE.md file should contain as few instructions as possible - ideally only ones which are universally applicable to your task.

コードスタイルはLinterに任せる

コードスタイルのルールをCLAUDE.mdに書くのは非効率だしコンテキスト量を圧迫したくない。
LLMより従来のLinterやFormatterの方が高速で確実だ。代わりにHooksを設定して、ファイル編集後に自動でPrettierやESLintを実行させるのがよさそう。
完全に受け売りだが尊敬している先輩エンジニアがBiomeを激推ししていたこともあり、自分はBiomeを好んで使っている。
create-next-appでBiomeが選べるようになっているあたり、彼の考えは正しかったみたいだ。

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "editFile",
        "command": "bunx prettier --write $FILE && bunx eslint --fix $FILE"
      }
    ]
  }
}

プロンプトの言語について

正直CLAUDE.mdを日本語で書くか英語で書くかは悩みどころだった。調べてみると、プロンプトとコンテンツの言語は一致させた方が精度が上がるという研究がある。

ただし、コード生成や論理推論のようなタスクは言語に依存しにくい。結局、以下のようなハイブリッドに落ち着いた。

会話の指示やワークフロー → 日本語（日本語で出力させたいので）
コマンド → 英語のまま
Plan Mode → 英語のまま（元々英語で効果が検証されている）

そもそもClaudeは日本語の理解力がはちゃめちゃに高い気がしているので、ところどころで英語と日本語を織り交ぜる某大柴のような記法をしない限りは致命的な問題はでない気がしている。
もしこれがいいよ！という意見があればぜひ教えていただきたい。

実際に使ってみた感想

入れたばかりでなんとも言えない。
pr-preview-toolkitの時のような驚きに出会えて、かつ僕の筆が乗っていたら追記しようと思う。

まとめ

Vercel Agent Skillsのインストール方法と中身を紹介した。

npx add-skill vercel-labs/agent-skillsで一発インストール
5つのAIエージェントに一括で入る
vercel-react-best-practicesは45のパフォーマンス最適化ルール
web-design-guidelinesはUIデザインのガイドライン

ReactやNext.jsで開発している人は入れておいて損はないと思う。
他にもこんなSkillsがあったよ！自分はこれを使っている！という意見があればぜひお聞かせ願いたい。

参考リンク

Vercel Blog - Introducing: React Best Practices
https://vercel.com/blog/introducing-react-best-practices
Vercel Design Guidelines
https://vercel.com/design/guidelines
GitHub - vercel-labs/agent-skills
https://github.com/vercel-labs/agent-skills
Anthropic - Claude Code Best Practices
https://www.anthropic.com/engineering/claude-code-best-practices
HumanLayer - Writing a good CLAUDE.md
https://www.humanlayer.dev/blog/writing-a-good-claude-md