Gaudiy でフロントエンドエンジニアをやっていますkotoriです！
この記事は#GauDev Advent Calendar 2025 の12日目の記事です🔥

はじめに

Gaudiy では AI の活用が推奨されており、ほとんどの開発者が Claude Code を業務に利用しています💪

Claude Code を日々使っていると「この手順、毎回 Claude に指示・説明してるな…」と思うことありませんか？

• コンポーネントを実装するときのお決まりのパターン
• CLAUDE.md に書いても忘れられたり無視されたり

こういった課題を解決し、繰り返し使うワークフローを定義して、チームで共有できる のがClaude Skills です🎉

特に UI 実装では、Figma を見ながら「この margin の px は...」「この色・フォントサイズは Design Token のどれだっけ...」と逐一確認する手間がありますよね。こういったFigma → コードの落とし込みを自動化する Skill を作ったことで、デザインデータの抽出から実装まで、高速かつ正確に進められるようになりました！👏👏

この記事では、独自で実装した Figma 連携 Skill を例に Claude Skills の活用方法を紹介していきます！

Claude Skills とは

2025年10月 に Anthropic が発表した、比較的新しい機能です。

公式ドキュメントによると

指示書（SKILL.md）、メタデータ、オプションのサポートファイル（スクリプト、テンプレート）をパッケージ化したもの

要はClaude の機能を拡張するモジュール です。

肝はModel-invoked（モデル駆動） なところです。ユーザーが明示的に呼び出さなくても、Claude が文脈を読んで勝手に適切な Skill を選んで使ってくれます☺️

Slash Commands との違い

「それって Slash Commands と何が違うの？」と思うかもしれません🤔

例えば：

• Slash Commands:/review と打ってコードレビューを実行
• Skills: 「この Figma を実装して」と言えば、Figma 関連の Skill が自動で発動

段階的開示（Progressive Disclosure）

Skills はトークン節約のために段階的開示 で動きます。

1. 起動時: 全 Skill のメタデータ（name, description）をロード
2. トリガー時: マッチした Skill の SKILL.md を読み込み
3. 必要時: 参照ファイルやスクリプトを読み込み

使わない Skill でコンテキストを食うことはありません！

課題：Figma MCP のトークン問題

Framelink MCP とは

Figma のデザインデータに Claude Code からアクセスできる MCP サーバーです。

https://github.com/GLips/Figma-Context-MCP

// .mcp.json{"mcpServers":{"framelink":{"command":"npx","args":["-y","figma-developer-mcp","--stdio"],"env":{"FIGMA_API_KEY":"${FIGMA_API_KEY}"}}}}

MCP を設定すると、Claude が Figma のデザインデータに直接アクセスできるようになります。

Figma API キーの取得：

1. Figma Settings にアクセス
2. Personal access tokens セクションで Generate new token をクリック
3. トークン名を入力して生成
4. 生成されたトークンを環境変数FIGMA_API_KEY に設定、または args で--figma-api-key=YOUR-KEY として指定

でも問題がある

Figma の巨大なデザインデータを扱うと、トークン消費が膨大になります。
1回の取得で約 100,000 トークン 消費することもザラにあります。

「Figma見て実装して」   ↓Figma データ取得（100K トークン消費）   ↓「ここ修正して」   ↓もうコンテキストがパンパン…

せっかくの便利な MCP が、トークン消費で実用的に使えません😇

解決：Sub Agent パターン

アイデア：Sub Agent で処理して要約だけ返す

Claude Code にはTask ツール（Sub Agent） があります！

Sub Agent は独立したコンテキストで動きます。ここで Figma データを処理して、実装に必要な情報だけ要約して返せば、メインセッションを汚さずに済みます。

depth オプションと再帰的取得

Framelink MCP のget_figma_data には depth オプションがあります。これは Figma のノード階層をどこまで深く取得するかを制御するパラメータです。

// depth=1: 直下の子ノードのみmcp__framelink__get_figma_data({ fileKey, nodeId, depth:1})// depth=4: 4階層まで取得（より詳細だが、トークン消費大）mcp__framelink__get_figma_data({ fileKey, nodeId, depth:4})

問題は、depth を大きくするとトークン消費が指数的に増えることです。depth=4 で画面全体を取得しようとすると、簡単に 100,000 トークンを超えます😇

Conservative Recursive Approach（段階的再帰取得）

そこで、Sub Agent 内で再帰的にデータを取得 する戦略を試してみることにしました。

1. Step 1: まず depth=1 で全体構造を把握
2. Step 2: 必要な子ノードだけを個別に取得
   • COMPONENT ノード → depth=3
   • SCREEN ノード → depth=4
   • その他 → depth=2
3. Step 3: トークンエラーが出たら depth を下げて再試行
4. Step 4: 取得したデータをマージ

Sub Agent が内部で複数回 MCP を呼び出してデータを組み立てますが、メインセッションには要約だけが返るので、コンテキストは汚れません！

Main Session (500 tokens)    ↓ Task 起動Sub Agent Session    ├─ mcp__framelink__get_figma_data (depth=1) → 5,000 tokens    ├─ mcp__framelink__get_figma_data (depth=3) → 15,000 tokens    ├─ mcp__framelink__get_figma_data (depth=4) → 30,000 tokens    ├─ データをマージして処理    ├─ ファイルに出力    └─ サマリーのみ返却 → 500 tokens         ↓Main Session (1,000 tokens) ← 実装に集中できる！

実際に試してみた

同一のそれなりに大きい Figma デザインで両方のパターンを試してみました。

直接呼び出しの場合：

The tool output was truncated. If this MCP server provides pagination...

出力が 25,000 トークンを超えてトランケートされました。必要な情報が欠落してしまいます。

Sub Agent パターンの場合：

Sub Agent 内で Figma データを取得・処理し、詳細なデザインデータは全て Markdown ファイルとして出力。メインセッションには要約のみ（約 500 トークン）が返ってきます。

残りの 50,000+ トークンは Sub Agent 内で消費されているため、メインセッションのコンテキストは圧迫されません！

結果：99% のトークン削減

Sub Agent 内では 50,000+ トークン消費していますが、メインセッションには 500 トークンしか流れません。

Conservative Recursive Approach のメリット：

• データの完全性を保ちつつ、メインセッションのコンテキストを節約
• トークンエラーが出ても自動でリトライ（depth を下げる）
• 必要なノードだけ深く取得する効率的な戦略

これで Figma 連携が実用的になりました🎉

ただ、この「Sub Agent を使う」「再帰的に取得する」というパターンを毎回説明するのは面倒ですよね。ここで Claude Skills の出番です！

Skill の作り方

公式の skill-creator を使う

Anthropic が提供しているskill-creator Skill を使うと、対話形式で Skill の雛形を生成できます。

# インストール/plugin marketplaceadd anthropics/skills

または、Claude に「https://github.com/anthropics/skills/tree/main/skills/skill-creator を参照して新しい Skill を作りたい」と言うだけでも使えます。

「新しい Skill を作りたい」と言うだけで、skill-creator が対話形式で以下を聞いてくれます：

• Skill 名
• 説明文
• 主な機能
• 必要な参照ファイル

最終的に、適切なディレクトリ構造と SKILL.md を生成してくれます。

手動で作る場合

もちろん手動でも作れます。基本構造はシンプルです。

my-skill/├── SKILL.md          # 必須└── references/       # 任意    └── detail.md

SKILL.md には最低限これだけあればおｋです。

---name: my-skilldescription: この Skill が何をするか、いつ使うかを具体的に---## Skill の説明### 手順1. ステップ12. ステップ2

description が重要：Claude がこれを見て自動発動するかを判断するので、具体的なキーワードを含めましょう。

より詳しい Skill の作り方は、公式サポートページも参考にしてください。

Skill の中身を見てみる

ここではfigma-framelink Skill を例に、実際の中身の一部を見ていきます。

ディレクトリ構造

figma-framelink/├── SKILL.md          # Skill 定義（メイン）└── references/       # 参照ドキュメント    ├── typography-extraction.md    ├── image-svg-handling.md    └── system-ui-exclusion.md

SKILL.md の構造

---name: figma-framelinkdescription: Guide for extracting Figma design data using Framelink MCP   and reflecting it in implementation. Use when you need to fetch Figma   designs, extract design tokens, download assets, or implement UI based   on Figma specifications. Always use Sub Agent pattern.---## Figma Framelink Skill### Critical Rules- 必ず Sub Agent で実行する- 結果は要約して返す- メインセッションで直接 MCP を呼ばない## Workflow### Pattern 1: シンプル取得（画面リストやメタデータの取得）### Pattern 2: 詳細取得（Typography、色、アセットの抽出）

description には「いつ使うか」を具体的に書くことで、Claude が自動で適切なタイミングで発動できるようになります。

実践テクニック

Typography 抽出

Figma API は TextStyle の参照名しか返しません。実際のフォントサイズや行間などの詳細情報は別途取得する必要があります。

例えば、TEXT ノードは"textStyle": "Body/Medium" のような参照名だけを持っていて、実際のfontSize: 14px やfontWeight: 500 といった値は Design Token として別の場所に定義されているケースがあります。

この参照を解決して Design Token として抽出する処理を Skill に書いておくことで、Claude が自動で正しい Typography 情報を取得できるようになります。

SVG/画像アセット処理

Figma API は IMAGE-SVG/VECTOR ノードのメタデータのみを返し、実際の SVG パスデータは含まれていません。

メタデータから形状を推測すると誤った実装になるリスクがあるため、IMAGE-SVG/VECTOR ノードは必ず画像としてダウンロードするよう Skill に明記しています。

## アセット処理ルール1. IMAGE-SVG/VECTOR ノードを検出2. メタデータ（サイズ、名前）から用途を判断3. MCP の download_figma_images で画像として取得4. CSS での近似は禁止（形状の誤認識リスク）

System UI の除外

Figma デザインには、iOS のホームインジケータ（画面下部の横棒）や Android のナビゲーションバーなど、OS が描画する UI 要素が含まれていることがあります。

これらは実装する必要がない要素です。Claude が実装してしまわないよう、Skill に除外ルールを明記しておきます。

## System UI 除外ルール❌ 実装しない要素：- iOS ホームインジケータ- Android ナビゲーションバー- ステータスバー（時刻・バッテリー表示）- セーフエリア境界✅ 実装する要素：- カスタムナビゲーション- アプリ固有のボタン・アイコン- コンテンツエリアのデザイン

プロジェクトごとに拡張する

汎用 Skill → プロジェクト固有 Skill

共通リポジトリで管理しているfigma-framelink Skill は汎用的に作ってあります。

実際のプロジェクトでは、これを技術スタックに合わせて拡張 して使います。

## 共通 Skill（汎用）~/.claude/skills/figma-framelink/## プロジェクト固有 Skill（拡張）プロジェクト/.claude/skills/my-figma/

拡張例：Panda CSS + Park UI プロジェクト

あるプロジェクトで使ってる技術スタックです。

• CSS: Panda CSS
• UI Components: Park UI

この場合、figma-framelink を内部で呼び出しつつ、プロジェクト固有のルールを足した Skill を作ります。

---name: my-figmadescription: Project-specific workflow for implementing Figma designs   with Panda CSS and Park UI. Extends figma-framelink skill with   design system mappings and component recipes.---## Workflow### Step 1: figma-framelink を呼び出し### Step 2: Panda CSS 形式への変換| Figma| Panda CSS||-------|-----------|| Colors|`panda-config/colors.ts`|| Typography|`panda-config/fonts.ts`|### Step 3: Park UI コンポーネントマッピング| Figma| Park UI||-------|---------|| Button|`<Button>` + recipe|| Input|`<Input>` + recipe|### Step 4: Chrome DevTools MCP で視覚確認

実装前に Figma の構造を分析させたり、実装後に Chrome DevTools MCP で視覚確認を必須化することで、実装の精度を高めています。

拡張のポイント

1. 汎用 Skill を呼び出す - 共通処理は再利用
2. Design System との対応付け - Design System があれば、Figma の Design Token やコンポーネントとの対応を定義
3. 既存プロジェクトへの導入 - Claude にコードベースを分析させて、既存の構造に合わせた Skill を生成

Skill を階層構造にすることで、共通処理は使い回しつつプロジェクト固有の設定だけ上書きできます。

Skills の配布方法

Skills を共有する方法は主に 2 つあります📦

方法 1: Plugin として配布（推奨）

Plugin として Skills をパッケージ化すると、チーム全体に簡単に配布できます。

marketplace.json でパッケージ化

プロジェクトルートにmarketplace.json を作成

{"name":"my-team-skills","plugins":[{"name":"frontend-skills","skills":["./figma-framelink"]}]}

これで、複数の Skill をまとめて配布できます。

インストール手順

# Marketplace を追加/plugin marketplaceadd my-org/my-skills# Plugin をインストール/plugininstall my-skills@my-org

mkdir-p ~/.claude/skills# シンボリックリンクを作成（推奨：更新が自動反映される）ln-s ~/.claude/plugins/marketplaces/my-skills/figma-framelink ~/.claude/skills/# または、コピーでも可（ただし更新時に再コピーが必要）cp-r ~/.claude/plugins/marketplaces/my-skills/figma-framelink ~/.claude/skills/

詳細は公式 Plugin ドキュメント を参照してください。

方法 2: Git リポジトリで共有

よりシンプルな方法として、プロジェクトの.claude/skills/ に配置して Git にコミットすれば、チームメンバーがgit pull するだけで自動的に利用可能になります。

追加の設定やインストール作業は不要です。

実際に使ってみて感じた課題

Skills を実際に運用してみて、いくつか気になった点がありました。

自動的に使ってくれないことがある

Skills は description を元に Claude が自動判断するのですが、必ずしも期待通りに発動しません😭

対策:

• description に具体的なトリガーワードを含める
• 「xxx Skill を使って」と明示的に指示する
• セッションの最初に使用可能な Skills を Claude に確認させる

プラグインのインストールだけでは使えない

前述の通り、公式ドキュメント通りにインストールしても、Skill が~/.claude/skills/ に自動配置されません😭

Figma 通りに実装されないことがある

一発で完璧に実装されないことがあります。気になる箇所は Figma の URL を指定して Skill で再確認・調整する作業が必要になる場合があります。

ただ、Figma と大きくズレることはなく、手動で全て実装するよりはるかに効率的です！Chrome DevTools MCP との併用で視覚的な差分確認も効率化できています。

まとめ

この記事では、Claude Skills を使って Figma → 実装のワークフローを自動化する方法を紹介しました。

実現できたこと

• UI 実装の高速化: Figma データの抽出から Design Token マッピングまで自動化
• トークン効率化: Sub Agent パターンで 99% のトークン削減（100,000 → 500 トークン）
• チーム共有: 繰り返しのワークフローを Skill として定義・配布

「毎回同じこと説明するの面倒だな」と思ったら、それは Skill 化のチャンスです！

AI を使ったコーディングは今や当たり前になりつつありますが、その先の段階として、いかに他のツールと連携して効率化するか、どうやって再利用性を高めるか が重要になってきていると感じています。Claude Skills はその一つのアプローチだと思います👍

参考リンク

• Claude Code Skills ドキュメント
• anthropics/skills（公式リポジトリ）

#GauDev Advent Calendar 2025 明日の担当はSandeepさんです！