Vercel公式SKILLSを導入してみた

はじめに：SKILLSの可能性に気づいた日

先日、Claude CodeのSKILLSシステムについて調べていたとき、ふと気になることがありました。

「公式が推奨するSKILLSの形式はわかった。でも、実際にプロダクション環境で使われているSKILLSって、どんな構造になっているんだろう？」

そう思ってGitHubを探索していると、興味深いリポジトリを見つけました。

vercel-labs/agent-skills

Vercel Engineeringチームが、自社のReact/Next.jsパフォーマンス最適化の知見を「AIエージェント向けスキル」として公開していたのです。

これは面白い。早速導入してみることにしました。

Vercel agent-skillsとは何か

公開されているスキル

vercel-labs/agent-skillsリポジトリには、現時点で2つのスキルが公開されています。

1. vercel-react-best-practices

Vercel Engineeringチームが蓄積してきたReact/Next.jsのパフォーマンス最適化ガイドラインです。45のルールが8つのカテゴリに分類されており、それぞれに「CRITICAL」「HIGH」「MEDIUM」「LOW」といったインパクトレベルが付与されています。

正直、このスキルを見たとき少し驚きました。45ものルールを、優先度付きで整理しているのです。しかも、それぞれのルールには「なぜそうすべきか」「悪い例」「良い例」が明確に記述されています。

2. web-design-guidelines

こちらはUIレビュー用のスキルです。アクセシビリティ、パフォーマンス、UXに関する100以上のルールを含んでおり、「UIをレビューして」「アクセシビリティをチェックして」といった指示で発動します。

興味深いのは、このスキルが外部URLから最新のガイドラインをフェッチする設計になっていること。ルールが更新されても、スキルファイル自体を書き換える必要がないのです。

なぜVercelがSKILLSを公開したのか

Vercelは、Next.jsの開発元として、膨大な数のReactアプリケーションのパフォーマンス問題を見てきました。「こうすれば速くなる」「これはやってはいけない」という知見が、社内には山のように蓄積されているはずです。

しかし、その知見をドキュメントとして公開しても、開発者が毎回参照するのは現実的ではありません。特に、締め切りに追われているときは、パフォーマンスより「とりあえず動くこと」を優先してしまいがちです。

SKILLSという形式で公開することで、AIが自動的にベストプラクティスを適用してくれるようになります。開発者は意識しなくても、AIがパフォーマンスを考慮したコードを生成してくれる。これは、知見を広める方法として非常に賢いアプローチだと思いました。

実際にインストールしてみる

add-skillツールの登場

Vercelは、スキルのインストールを簡単にするCLIツールも公開しています。

npx add-skill vercel-labs/agent-skills --list

このコマンドを実行すると、利用可能なスキルの一覧が表示されます。

◇  Available Skills

   vercel-react-best-practices
     React and Next.js performance optimization guidelines...

   web-design-guidelines
     Review UI code for Web Interface Guidelines compliance...

インストールも簡単です。

npx add-skill vercel-labs/agent-skills \
  --skill vercel-react-best-practices \
  --skill web-design-guidelines \
  -y

驚いたのは、このツールが複数のAIエージェントを自動検出すること。私の環境では、以下の3つのエージェントにスキルがインストールされました。

Claude Code（.claude/skills/）
Gemini CLI（.gemini/skills/）
GitHub Copilot（.github/skills/）

つまり、一度のコマンドで、使っているすべてのAIコーディングツールにスキルを導入できるのです。これは便利ですね。

インストール後のディレクトリ構造

インストール後、.claude/skills/ディレクトリを確認してみました。

.claude/skills/
├── vercel-react-best-practices/
│   ├── SKILL.md           # スキル本体
│   ├── AGENTS.md          # 全ルール統合版
│   └── rules/             # 個別ルールファイル（45個）
│       ├── async-parallel.md
│       ├── async-defer-await.md
│       ├── bundle-barrel-imports.md
│       └── ...
└── web-design-guidelines/
    └── SKILL.md

vercel-react-best-practicesは、SKILL.mdに加えてrules/ディレクトリを持っています。45のルールがそれぞれ独立したMarkdownファイルとして管理されているのです。

SKILL.mdの構造を読み解く

フロントマター

Vercelのスキルは、公式フォーマットに準拠しています。

---
name: vercel-react-best-practices
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns.
license: MIT
metadata:
  author: vercel
  version: "1.0.0"
---

必須フィールドのnameとdescriptionに加えて、licenseやmetadataといった拡張フィールドが含まれています。これらは公式フォーマットの範囲内での拡張であり、問題ありません。

特に注目すべきはdescriptionの書き方です。

"This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns."

いつ使うべきかが明確に記述されています。これにより、AIは「今このスキルを参照すべきかどうか」を判断できます。

ルールの優先度設計

SKILL.mdの本文には、8つのカテゴリが優先度順に並んでいます。

優先度	カテゴリ	インパクト
1	Eliminating Waterfalls	CRITICAL
2	Bundle Size Optimization	CRITICAL
3	Server-Side Performance	HIGH
4	Client-Side Data Fetching	MEDIUM-HIGH
5	Re-render Optimization	MEDIUM
6	Rendering Performance	MEDIUM
7	JavaScript Performance	LOW-MEDIUM
8	Advanced Patterns	LOW

この設計が秀逸だと感じました。

AIがコードを生成・レビューするとき、すべてのルールを同じ重要度で扱うのではなく、CRITICALなルールを優先的に適用できます。「まずはウォーターフォールを排除し、次にバンドルサイズを最適化する」という、実際の開発でも重要な優先順位が反映されているのです。

個別ルールの書き方

ルールファイルの構造

rules/async-parallel.mdを見てみましょう。

---
title: Promise.all() for Independent Operations
impact: CRITICAL
impactDescription: 2-10× improvement
tags: async, parallelization, promises, waterfalls
---

フロントマターには、タイトル、インパクトレベル、具体的な改善効果（2-10倍！）、タグが含まれています。

本文は非常にシンプルです。

## Promise.all() for Independent Operations

When async operations have no interdependencies,
execute them concurrently using `Promise.all()`.

**Incorrect (sequential execution, 3 round trips):**

const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

**Correct (parallel execution, 1 round trip):**

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

悪い例と良い例が明確に対比されています。AIは、この形式のルールを見て「このパターンを見つけたら修正を提案する」という行動を取れます。

ルールの粒度

45のルールを眺めていると、その粒度が絶妙であることに気づきます。

広すぎない: 「パフォーマンスを意識しましょう」のような曖昧なルールはありません。すべて具体的なコードパターンに落とし込まれています。

狭すぎない: 特定のライブラリのバージョンに依存するようなルールもありません。React/Next.jsの一般的なパターンとして適用できます。

この粒度設計は、SKILLSを作成する際の参考になります。

web-design-guidelinesの面白い設計

外部リソースの動的フェッチ

web-design-guidelinesスキルは、ルールを外部から取得する設計になっています。

## Guidelines Source

Fetch fresh guidelines before each review:

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

Use WebFetch to retrieve the latest rules.

これは興味深いアプローチです。

ガイドラインが更新されても、スキルファイル自体を更新する必要がありません。AIは毎回最新のルールを取得してレビューを実行します。

ただし、この設計には注意点もあります。

ネットワーク接続が必要
外部URLが変更されると動作しなくなる
オフライン環境では使えない

用途に応じて、ルールを埋め込むか外部参照するか、選択する必要があるでしょう。

argument-hintフィールド

metadata:
  argument-hint: <file-or-pattern>

このフィールドは、スキルの呼び出し方をユーザーに示すヒントです。「ファイルまたはパターンを引数として渡してください」という意味ですね。

vcbookとの関連性

本記事を読んでいる方の中には、「Claude Code × Vibe Coding 体系的教科書」シリーズを読まれた方もいるかもしれません。

そのシリーズの第4章「SKILLSアプローチ」では、SKILLSの基本概念と設計思想を解説しました。

段階的開示（Progressive Disclosure）
インデックス層と本文層の分離
descriptionの重要性
When to Useセクションの書き方

Vercelのスキルは、これらの原則を忠実に実装した実践例と言えます。

特に注目すべきは、45ものルールを持ちながら、SKILL.md本体は比較的コンパクトに保たれていること。個別ルールをrules/ディレクトリに分離することで、段階的開示を実現しています。

実際に使ってみた感想

導入後の変化

スキルを導入してから、いくつかの変化がありました。

1. コードレビューの質が上がった

「このコードをレビューして」と依頼すると、以前は一般的なコメントが多かったのですが、導入後は具体的なパフォーマンス改善提案が増えました。

例えば、連続したawaitを見つけると「これらは独立した処理なので、Promise.all()で並列化できます（2-10倍の改善が期待できます）」といったコメントが返ってきます。

2. 新規コード生成時の品質向上

新しいコンポーネントを作成するとき、最初から最適化されたパターンが使われるようになりました。バレルファイルからの直接インポート、適切なサスペンス境界の配置など、以前なら後から修正していたポイントが最初からカバーされています。

3. 学習効果

正直、45のルールの中には知らなかったものもありました。content-visibilityCSSプロパティを使った長いリストの最適化、toSorted()を使ったイミュータブルなソートなど、AIのコード生成を見て「へえ、こんな方法があるんだ」と学ぶこともあります。

注意点

一方で、注意すべき点もあります。

過度な最適化: すべてのルールを適用する必要はありません。特にLOWインパクトのルールは、可読性とのトレードオフを考慮すべきです。

コンテキストの肥大化: 45のルールを持つスキルは、それなりのコンテキストを消費します。大規模なコードベースで作業するときは、意識しておく必要があります。

ルールの鮮度: Vercelのルールは定期的に更新されます。npx add-skillを時々実行して、最新版に更新することをお勧めします。

具体的なルールを深掘りしてみる

せっかくなので、いくつかの具体的なルールを詳しく見てみましょう。

Eliminating Waterfalls（ウォーターフォール排除）

このカテゴリがCRITICALに設定されているのには理由があります。ウォーターフォール（連続的な待機）は、Webアプリケーションのパフォーマンスを最も大きく損なう要因の一つだからです。

async-suspense-boundariesというルールでは、React 18のSuspenseを使ったストリーミングが推奨されています。

// 悪い例：すべてのデータが揃うまで何も表示されない
async function Page() {
  const data = await fetchAllData() // 3秒かかる
  return <Content data={data} />
}

// 良い例：重要な部分から順次表示
async function Page() {
  return (
    <>
      <Header /> {/* 即座に表示 */}
      <Suspense fallback={<Loading />}>
        <MainContent /> {/* データ準備でき次第表示 */}
      </Suspense>
    </>
  )
}

これにより、ユーザーは「何か起きている」ことを早い段階で認識でき、体感速度が大幅に向上します。

Bundle Size Optimization（バンドルサイズ最適化）

bundle-barrel-importsは、私自身も気づかずにやってしまっていたアンチパターンでした。

// 悪い例：バレルファイルからインポート
import { Button } from '@/components'
// → componentsディレクトリ全体がバンドルに含まれる可能性

// 良い例：直接インポート
import { Button } from '@/components/Button'
// → 必要なファイルだけがバンドルされる

バレルファイル（index.tsで再エクスポートするパターン）は便利ですが、ツリーシェイキングが効かない場合があります。特に、副作用のあるモジュールが含まれていると、使っていないコードまでバンドルされてしまいます。

JavaScript Performance（JavaScript パフォーマンス）

js-set-map-lookupsは、O(n)をO(1)に改善するテクニックです。

// 悪い例：配列のincludes（O(n)）
const allowedIds = ['a', 'b', 'c', ...]
if (allowedIds.includes(id)) { ... }

// 良い例：Setのhas（O(1)）
const allowedIds = new Set(['a', 'b', 'c', ...])
if (allowedIds.has(id)) { ... }

データ量が少ないときは差を感じませんが、1000件、10000件と増えていくと、この違いが顕著になります。

自分のプロジェクトにSKILLSを作る

Vercelのスキルを参考に、自分のプロジェクト固有のスキルを作ってみるのも良いでしょう。

参考にすべきポイント

1. 優先度を明確にする

すべてのルールを同じ重要度にせず、CRITICAL/HIGH/MEDIUM/LOWのようなレベル分けを検討してください。AIがどのルールを優先すべきか判断できます。

2. 悪い例と良い例を対比させる

「こうすべき」だけでなく「こうしてはいけない」を明示することで、AIの理解度が上がります。

3. 具体的な改善効果を記述する

「2-10倍の改善」のように、定量的な効果を記述すると、ルールの重要性が伝わります。

4. ルールの粒度を適切に保つ

広すぎず狭すぎず、具体的なコードパターンに落とし込める粒度を心がけてください。

スキル作成の実践例

vcbookシリーズで紹介した方法を使って、Claudeにスキルの骨格を作らせることもできます。

あなた：このプロジェクトのReactコンポーネントを分析して、
       一貫したパターンを見つけて、
       SKILL.mdのドラフトを作ってくれ。
       Vercelのreact-best-practicesを参考にして、
       優先度付きで整理してほしい。

まとめ

Vercelのagent-skillsを導入してみて、いくつかの学びがありました。

1. 企業の知見をSKILLSとして公開する価値

Vercelのように、自社の知見をSKILLSとして公開することで、開発者コミュニティ全体の底上げに貢献できます。しかも、ドキュメントと違って「AIが自動的に適用してくれる」という形で。

2. スキル設計のベストプラクティス

45のルールを優先度付きで整理し、個別ファイルに分離する。外部リソースを動的にフェッチする。これらは、大規模なスキルを設計する際の参考になります。

3. add-skillエコシステムの可能性

複数のAIエージェントに一度にスキルをインストールできるadd-skillツールは、スキルの配布・共有を容易にします。今後、さまざまな企業やコミュニティがスキルを公開するようになれば、AIコーディングの質が全体的に向上していくでしょう。

参考リンク

vercel-labs/agent-skills - Vercel公式スキルリポジトリ
vercel-labs/add-skill - スキルインストールCLI
VoltAgent/awesome-claude-skills - 80以上のスキルコレクション
Claude Code × Vibe Coding 体系的教科書 - SKILLSの基本概念を解説したシリーズ

本記事は「Claude Code × Vibe Coding 体系的教科書」シリーズの関連記事です。SKILLSの基本概念については、シリーズ第4章「SKILLSアプローチ」をご参照ください。

Vercel公式SKILLSを導入してみた ― React/Next.jsパフォーマンス最適化の知見をAIに教え込む