🍭
デザインシステムを丸ごと Skills にする

mugi
2026/04/08に公開
frontend
tech
 デザインシステムを Skills にしたら使いやすくなったサイボウズのプロダクトである kintone では、社内向けに kintone Design System と呼ばれるデザインシステムが提供されています。
https://note.com/amishiratori/n/n0d8467106f27
AI Agent を用いた開発向けに、このデザインシステムの Skills 化を試みたところ、提供側・利用側ともに非常に取り回しやすい形となったため、事例として紹介します。

 デザインシステム x MCPデザインシステムをコーディング用の AI Agent から活用する際、一例としては MCP の提供が挙げられます。

一時期話題になった印象で、個人的にも、以下の記事を参考にさせて頂いた記憶があります。
https://zenn.dev/ubie_dev/articles/f927aaff02d618
https://zenn.dev/layerx/articles/7e9f87fca65e94

 なぜ MCP が効いたかデザインシステム x MCP のパターンが普及した際の背景事情として、エージェントにナレッジを与える方法は限られていた、ということが挙げられます。
AGENTS.md (CLAUDE.md)
Rules
その他ドキュメントとしての定義
コンテキストが大きくなってくると、あらかじめ入れた情報が薄れてしまい、適切に情報の取捨選択を行ってくれないような振る舞いをするケースが多くありました。
特にデザインシステムの場合、次のように含まれる情報が大きくなりやすいです。
デザインシステムが提供する範囲
コンポーネントの一覧
デザイントークンの一覧
それぞれのコンポーネントなどの詳細な使い方
利用におけるベストプラクティス
遵守すべきデザインガイドライン
など
一方で MCP では必要に応じて情報を取得します。いわゆる段階的開示（Progressive Disclosure）の形となり、作業の中で必要なタイミングで鮮度や密度の高い情報を利用しやすいのが大きなメリットでした。
自分も過去に似たようなMCPを構築したことがありましたが、実際、わりと精度高く活用してくれる印象がありました。

 デザインシステムの MCP はどういう仕組みだったか？「必ずこういうものだ」という定義があるわけではないですが、世の中のデザインシステムのMCP構築事例を見てみると、概ね次のような機能を持つことが多いようです。
基本的なデザインシステムの概要を返す
コンポーネント/デザイントークンの一覧を返す
コンポーネント/デザイントークンの詳細を返す
Storybookやソースコードなどを参考情報としてそのまま返す
一発で目的の情報を得るようなものではなく、最初は粒度の粗い情報（全体概要や一覧など）を取得させ、次に目的に沿ってさらに詳細情報を取得させるような仕組みです。
また、最終的に Storybook のコードをそのまま返す、というケースが多いのも特徴かなと思います。これはつまり、一定の整形などは生じるかもしれませんが、実際のところ 「すでに存在する情報をそのまま返す」 というだけで望む形になっていたとも言えます。

 MCP の辛いところしかし、MCP では恩恵だけではなく、一部デメリットも存在していました。

 MCPサーバーの構築情報を返すためのMCPサーバーを何らかの方法で構築する必要があります。
ローカルサーバーとして立ち上げるのが手っ取り早いですが、何らかの方法で簡易的に起動する仕組みを用意する必要があります。リモートサーバーにすることで各位が起動するコストは低減できますが、今度はサーバー自体の運用が生じます。
また、そもそもMCPサーバー自体の設計・実装が必要で、実装後の更新も必要となります。

 コンテキストの圧迫設計にもよる部分があるため一概にそうとは言えませんが、MCP はコンテキストを圧迫しやすい、とも言われます。
目的の情報を得るために多くのツールの実行を伴うため、気がつけばコンテキストを大量に消費してしまった…ということが発生し得ます。

 Skills の登場昨今では、様々なナレッジを Agent Skills として整備することが一般的になりました。
https://agentskills.io/home
Skills の特徴として、次のようなものが挙げられます。
最初は name および description のみを参照する
必要に応じて SKILL.md の内容を参照する
さらに必要が生じたら、references/ などの中身を段階的に参照する
ここで、デザインシステム x MCP で嬉しかったポイントをおさらいしてみます。
一方で MCP では必要に応じて情報を取得します。いわゆる段階的開示（Progressive Disclosure）の形となり、必要な作業のタイミングでより鮮度や密度の高い情報を利用しやすくなります。
察しの良い方はお気付きかもしれませんが、デザインシステムの MCP に求めていた本質的なポイントの一部は、実は Skills が提供してくれるものがそっくりそのままマッチします。
つまり、Skills としてデザインシステムを参照できる仕組みを構築すれば、従来やりたかったことはそのまま実現できます。

 デザインシステム x Skillsということで、ようやく本題です。
弊社内で利用している kintone Design System において、どのように Skills 化したのかを見ていきましょう。

 構築した Skills の仕組み = リポジトリをそのまま持ってくるkintone Design System では、利用者が困ることがないよう、かなり潤沢かつ丁寧にドキュメントが整備されていました。
たとえば、次のようなドキュメントが用意されています。
デザインシステムの利用ガイドライン
コンポーネント利用時のセットアップ方法
すべてのコンポーネントの詳細な概要・使い方・Storybook でのサンプル
Decision Tree での利用可否判定
デザイントークンの概要・命名規則・利用ルール
アクセシビリティ上のガイドライン
UI開発における実装原則やベストプラクティス
コントリビューションガイド
など
これらのドキュメント自体も Storybook 上で MDX ファイルとして作成されており、ソースコードも含めて単一のリポジトリで集約管理されています。
次のようなイメージです。（解説のため大幅に簡略化し重要なポイントだけ表現しています。実際のものとは命名や階層はかなり異なります。）
docs/            - すべてのドキュメント
  README.mdx     - 各ドキュメントの概要
  〜.mdx
  guidelines/    - ガイドライン系のドキュメント
    README.mdx   - ガイドライン系ドキュメントの概要
    〜.mdx
  designTokens/  - デザイントークンに関するドキュメント
    README.mdx   - デザイントークン系ドキュメントの概要
    〜.mdx
  ...

components/      - デザインシステム提供のコンポーネント
  README.mdx     - コンポーネントの一覧と概要
  Button/
    index.tsx    - コンポーネントの実体
    stories/
      Button.stories.tsx - コンポーネントのストーリー
    docs/
      Button.mdx - コンポーネント毎の詳細なドキュメント

...
これをよく見ると、次のような特徴があることがわかります。
用途や役割に応じてディレクトリが切られている
それぞれに README.mdx のようなファイルが置かれており、階層ごとに内包物の一覧と概要が記載されている
README.mdx を辿りながら潜っていけばより詳細な情報に到達できる
もともとは人間が参照しやすいように整理していった結果、現在の構造に行き着いたものかと思われますが、この構造は MCP のときにも求められていた、段階的に詳細へ辿れる形にマッチする構造になっています。
つまり、Skills としてデザインシステムを活用してもらうことを考えた場合、むやみに Skills 向けに新しいドキュメントを書き足すよりも、リポジトリを手元に持ってきてもらってそれを上手く参照してもらうような仕組みが手っ取り早いのでは、と考えました。

 作成した Skills の例ということで、実際に作成した Skills は次のようなイメージです。

（実際のものを簡略化しています）
# kintone Design System

kintone プロダクト開発で kintone Design System のコンポーネント・デザイントークンを活用するためのナビゲーションスキル。

## Step 1: リポジトリのセットアップ

現在のプロジェクトが利用している kintone Design System のバージョンに合わせて、
kintone Design System リポジトリの該当バージョンをローカルキャッシュに取得する。

### 1-1. 利用バージョンの特定

プロジェクトの `package.json` から各パッケージのバージョンを読み取る。

````bash
read_version() {
  node -e "
    const pkg = require('./package.json');
    const v = pkg.dependencies?.['$1'] || pkg.devDependencies?.['$1'] || '';
    console.log(v.replace(/^[\^~>=<]*/, ''));
  "
}
KDS_VERSION=$(read_version '@organization-name/kintone-design-system')
````

バージョンが取得できない場合は、ユーザーに確認する。

### 1-2. クローンとチェックアウト

リポジトリをそれぞれキャッシュに利用バージョンのタグでチェックアウトする。

````bash
KDS_BASE="${XDG_CACHE_HOME:-$HOME/.cache}/kintone-Design-System-skills"

clone_and_checkout() {
  local repo="$1" dir="$2" version="$3"
  if [ -d "$dir/.git" ]; then
    git -C "$dir" fetch --tags 2>/dev/null || true
  else
    gh repo clone "$repo" "$dir" 2>/dev/null || true
  fi
  if [ -n "$version" ] && [ -d "$dir/.git" ]; then
    git -C "$dir" checkout "$version" 2>/dev/null || git -C "$dir" checkout main
  fi
}

clone_and_checkout @organization-name/kintone-design-system "$KDS_BASE/kintone-Design-System" "$KDS_VERSION"
```

クローン・チェックアウトに失敗した場合にはユーザーに確認し、解決策も提示する。

## Step 2: ドキュメントを辿る

`$KDS_BASE/kintone-Design-System/src/docs/` 配下にドキュメントが存在する。
各サブディレクトリの `README.mdx` を起点に、関連ドキュメントを辿る。

| ディレクトリ      | 起点ファイル | 概要                                            |
| ----------------- | ------------ | ----------------------------------------------- |
| `gettingStarted/` | `README.mdx` | 導入・セットアップ                              |
| `designTokens/`   | `README.mdx` | デザイントークンの概要と使い方                  |
| `guidelines/`     | `README.mdx` | デザイン・開発・ライティング・a11y ガイドライン |
| `history/`        | `README.mdx` | 歴史的経緯・設計判断の背景                      |

トップレベルにも概要ドキュメントがある（`introduction.mdx`, `kintone Design Systemとは？.mdx` 等）。
質問内容に応じて適切なディレクトリの `README.mdx` から読み進める。

## Step 3: コンポーネントを調べる

`$KDS_BASE/kintone-Design-System/src/components/` 配下にコンポーネントが配置されている。
カテゴリ別のサブディレクトリ構成になっているため、まずディレクトリ一覧で全体像を把握する。

各コンポーネントの詳細は以下のファイルから確認する：

- **`stories/*.stories.tsx`** — Props・バリエーション・使用例（最も実践的な情報源）
- **`docs/*.mdx`** — コンポーネントドキュメント（存在する場合）
Skills の作成は、ほぼ anthropics/skills の skill-creator にお任せしました。

https://github.com/anthropics/skills/tree/main/skills/skill-creator
利用側のバージョンに併せて、XDG Base Directory Specification に沿ったキャッシュディレクトリにリポジトリをチェックアウトさせており、その他はリポジトリ内の参照の仕方、いわばガイドマップのような情報だけを記載してあります。
あとは、もともとのリポジトリが README.mdx を利用して潜っていける仕組みになっているため、自動的に段階的な参照が実現されます。

 動作例試しに一部コンポーネントの仕様を Claude Code で確認してみた例です。
次のように、リポジトリ内の情報をベースに正しく情報が得られていますね。
ドキュメントやソースコードも、必要なものだけを段階的に参照しています。

 Skills 化によるメリットデザインシステムの情報を Skills として参照可能にする方法には、他にも次のような利点が考えられます。

 提供側のコストが低い結局のところ、今回の仕組みで提供側が最低限用意するものは SKILL.md のみです。必要に応じて補足情報用の references/ やリポジトリ操作用の scripts/ などを追加する可能性はありますが、そこまで大きいものにはならないでしょう。
デザインシステム側に更新があっても、全体の構造に大きな変化がない限りは、特に修正する必要はありません。（仮に構造の変化があったとしても、SKILL.md の修正で事足りるケースが大半だと思われます）
デザインシステムのリポジトリ自体が参照しやすい形で整理されていることが前提にはなりますが、それさえ満たせていれば、既存資産を最大限利用した形で、コスト低く有効活用できる仕組みを作れます。

 利用側が簡単に導入できる利用側では、利用する AI Agent の仕組みに則って、Skills を適切な位置に配備するのみです。MCP 用のローカルサーバーを起動する必要もなく、利用開始が非常に容易です。
また、Claude Code などであれば Slash Commands として明示的に呼び出せるようになるのも便利なポイントです。

 Skills 化から得られた学び = デザインシステムの構造は人間/AI共に重要今回の Skills 作成にあたって、もっとも重要だった部分は 「デザインシステムの構造が整理されていたこと」 です。
もともと人間が参照しやすいように設計されたものですが、その中でも次のような点から大きな恩恵を受けました。
役割ごとにフォルダとなっており、階層構造になっている
それぞれに README が存在し、階層ごとに一覧と概要が把握できる
深く潜るほどに詳細な情報となる
ドキュメントとコードが同じリポジトリ内に含まれている
ドキュメントが Markdown ベース (MDX) で記載されている
ちなみに、逆に言えば AI 向けに上記の形で整備すると人間からも参照しやすい形になる、とも言えるかもしれません。
Skills 作成を通じて、ナレッジやコードべースが綺麗に構造化されて管理されていることの重要性を改めて感じました。

 まとめもちろん今回の方法が常にベストというわけではなく、npm パッケージ内に Skills ないしはドキュメントを含めて配布する、といった方法なども考えられますし、チームやプロジェクトによって適切な方法は異なりそうです。
Skills での提供については、前提さえ整えばコスパが非常に良いのが最大の特徴かと思います。もしマッチしそう、という場合にはご参考にしていただければ幸いです。