デザインシステムをClaude Skillsとして実装する：kintone事例に学ぶAI対応ドキュメント設計

Tools

analyze-design-tokens

実は、これは SKILL.md という**テキストファイル**に過ぎません。

**Skills の利点**:

- **ローカルサーバー不要**: リポジトリに SKILL.md を配置するだけで完成
- **Git で管理**: バージョン管理が自動的に行われる
- **高速**: 事前にファイルを読み込むので、ネットワーク遅延なし
- **簡潔**: 複雑な認証や設定が不要
- **拡張性**: README.md との組み合わせで、柔軟に知識を増やせる

### 使い分けの判断基準

<table>
  <thead>
    <tr><th>特性</th><th>MCP</th><th>Skills</th></tr>
  </thead>
  <tbody>
    <tr><td>規模</td><td>大規模システム（複数サーバー）</td><td>中小規模〜個別プロジェクト</td></tr>
    <tr><td>更新頻度</td><td>リアルタイム同期が必要</td><td>Git push で十分</td></tr>
    <tr><td>チーム体制</td><td>DevOps 人員が確保できる</td><td>エンジニア主導</td></tr>
    <tr><td>セキュリティ</td><td>高度な認可制御が必要</td><td>リポジトリアクセス制御で足りる</td></tr>
    <tr><td>立ち上げコスト</td><td>高い（1-2週間）</td><td>低い（数時間）</td></tr>
    <tr><td>保守性</td><td>複雑（複数チームの協調）</td><td>シンプル</td></tr>
  </tbody>
</table>

**結論: デザインシステム の場合、Skills を選ぶべきです。** なぜなら、デザインシステムは「頻繁に変更される情報」ではなく、「ゆっくり進化する標準定義」だからです。

## SKILL.mdの設計原則

では、どうやって SKILL.md を設計すれば、AI が「使える」デザインシステムになるでしょう？ kintone Design System の実装から、3つの原則を抽出しました。

### 原則 1: 階層設計による参照連鎖

SKILL.md は、**入口** です。複雑な全情報を1ファイルに詰め込むのではなく、段階的に詳細へ誘導します。

**悪い例**（フラット構造）:
```markdown
# kintone Design System

## Button Component Props
- variant: "primary" | "secondary" | ...
- size: "sm" | "md" | ...
- disabled: boolean
- loading: boolean
- ... 延々と100項目

良い例（階層構造）:

# kintone Design System
 
## Quick Start
- [Button Component](./src/components/Button/README.mdx)
- [Form Component](./src/components/Form/README.mdx)
- [Layout Component](./src/components/Layout/README.mdx)
 
---
 
## Design Tokens
See [Design Tokens Guide](./docs/design-tokens.md)
 
## Architecture
See [Component Architecture](./docs/architecture.md)

各コンポーネントフォルダに「自分の README.mdx」を配置します。

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.stories.tsx
│   │   ├── Button.test.tsx
│   │   └── README.mdx  ← ここで詳細を説明
│   ├── Form/
│   │   ├── Form.tsx
│   │   └── README.mdx

AI は SKILL.md を読みながら、必要に応じて各 README.mdx を参照します。この構造により、AI のコンテキスト使用量を最小化しながら、詳細情報へのアクセスを確保できます。

原則 2: 自動検出可能なメタデータ

package.json や README の構造から、AI が「バージョン」「更新日時」「メンテナー」を自動検出できるように設計します。

{
  "name": "@kintone/design-system",
  "version": "2.5.3",
  "description": "Kintone Design System - Enterprise-grade React component library",
  "maintainers": [
    "Design Systems Team <design@cybozu.co.jp>"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/cybozu/kintone-design-system"
  },
  "keywords": [
    "design-system",
    "components",
    "react",
    "typescript",
    "ui-library"
  ]
}

SKILL.md の冒頭で、このメタデータを参照させます。

# kintone Design System
 
> Version: 2.5.3 (from package.json)
> Last Updated: 2026-04-08
> Maintained by: Design Systems Team
 
## Overview
This is the official component library for the Kintone product...

原則 3: 曖昧さを避ける明示的な説明

AI は、「省略された情報」「暗黙的なルール」を補完するのが苦手です。人間なら「これはボタンだから、クリック時に何か起こるんだろう」と推測できても、AI には明示的に教える必要があります。

悪い例（曖昧）:

### Button Component
A reusable button component. Can be primary, secondary, or danger.

良い例（明示的）:

### Button Component
 
**Purpose**: Used to trigger actions, submit forms, or navigate to other pages.
 
**When to use**:
- Form submission （フォーム送信時）
- Confirmation dialogs （確認ダイアログ）
- Navigation （ページ遷移）
 
**When NOT to use**:
- Do NOT use for links → use `<a>` tag or Next.js `<Link>`
- Do NOT use for toggle switches → use Toggle component
- Do NOT use for radio buttons → use RadioGroup component
 
**Props**:
- `variant`: Type of button
  - "primary": Main action (use only one per screen)
  - "secondary": Alternative action
  - "danger": Destructive action (delete, remove, etc.)
- `size`: Button dimensions
  - "sm": 32px height (use in compact layouts)
  - "md": 40px height (standard size)
  - "lg": 48px height (CTA buttons)
- `disabled`: Disables the button
  - When true: Click handler is not triggered
  - Reason: Use to prevent duplicate submissions

この方式により、AI は「どのコンポーネントを選ぶべき か」を正確に判定できます。

kintone Design System Skillsの実装詳細

では、実際の kintone Design System Skillsdはどう構成されているのか、詳しく見ていきます。

リポジトリ構造の設計

kintone-design-system/
├── SKILL.md                    ← AI の入口
├── README.md                   ← チーム・外部向け説明
├── package.json                ← メタデータ
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx       ← 実装
│   │   │   ├── Button.stories.tsx ← Storybook
│   │   │   ├── Button.test.tsx   ← テスト
│   │   │   └── README.mdx       ← AI が参照
│   │   ├── Form/
│   │   │   ├── Form.tsx
│   │   │   ├── Form.stories.tsx
│   │   │   ├── Form.test.tsx
│   │   │   └── README.mdx
│   │   └── ... （他のコンポーネント）
│   ├── tokens/
│   │   ├── colors.json         ← デザイントークン
│   │   ├── typography.json
│   │   ├── spacing.json
│   │   └── README.md
│   └── utilities/
│       ├── hooks/
│       └── helpers/
├── docs/
│   ├── design-tokens.md        ← トークン ガイド
│   ├── accessibility.md        ← アクセシビリティ
│   ├── contributing.md         ← 貢献ガイド
│   └── architecture.md         ← 設計説明
├── .storybook/
│   └── main.ts
└── storybook-static/           ← ビルド出力

特徴:

• 各コンポーネントが自己完結型（実装 + テスト + ドキュメント）
• JSON トークンが中央集約（色・フォント・スペーシング）
• SKILL.md が全体の地図（マップ）として機能

package.jsonからのバージョン自動検出

SKILL.md は、CI/CD パイプラインで「動的に生成される」部分があります。

// SKILL.md を動的に生成するスクリプト
const pkg = require('./package.json');
const fs = require('fs');
 
const skillContent = `# kintone Design System
 
Version: ${pkg.version}
Last Updated: ${new Date().toISOString().split('T')[0]}
 
## Components
 
${pkg.keywords.map(keyword => `- ${keyword}`).join('\n')}
`;
 
fs.writeFileSync('./SKILL.md', skillContent);

こうすることで、package.json を編集するだけで SKILL.md が自動更新され、AI は常に最新バージョンを参照できます。

Storybook 統合

kintone Design System には Storybook が統合されています。これは単なる「UI ブラウザ」ではなく、AI がコンポーネント の使い方を学ぶための教科書です。

// Button.stories.tsx
import { Button } from './Button';
 
export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    // Storybook AI Plugin が読み込む
    ai: {
      description: 'Primary action button for forms and dialogs',
      usage: 'Use for main actions. Only one per screen.',
    }
  }
};
 
export const Primary = () => <Button variant="primary">Click me</Button>;
Primary.parameters = {
  ai: {
    description: 'Primary button (main action)',
  }
};
 
export const Secondary = () => <Button variant="secondary">Cancel</Button>;

Storybook からエクスポートされるメタデータを、AI が参照します。

提供側・利用側のメリット

提供側（Design Systems Team）のメリット:

• GitHub リポジトリを push するだけで、AI が最新情報を参照開始
• バージョン管理が自動化される
• リポジトリのスター・フォーク数が増加（エコシステムの健全性）

利用側（開発チーム）のメリット:

• 「Button コンポーネントはどう使う？」という質問を AI に投げかけるだけで、正確なコード例が返ってくる
• コンポーネント の使い誤りが減少
• 新規プロジェクトの立ち上げが高速化

自分のデザインシステムをSkillsにする手順

では、あなたのデザインシステムを Claude Skills として実装するための、具体的な5つのステップを説明します。

Step 1: リポジトリ構造の整理（AI が読みやすいフォルダ構成）

まず現在のリポジトリを診断します。

# 現在のフォルダ構造を可視化
tree -L 3 src/components | head -30

理想的なフォルダ構成は、役割ごとに分離されているものです。

src/components/
├── Button/
│   ├── index.ts         ← export
│   ├── Button.tsx       ← 実装
│   ├── Button.test.tsx  ← テスト
│   ├── Button.stories.tsx ← Storybook
│   ├── README.mdx       ← AI がここを読む
│   └── styles.module.css
├── Form/
├── Card/
└── ... （他のコンポーネント）

もし現在の構造が異なる場合（例：styles が分散している）、以下の手順で整理します。

# 各コンポーネントを独立したフォルダに移動
mkdir -p src/components/Button
mv src/components/button.tsx src/components/Button/Button.tsx
mv src/components/button.test.tsx src/components/Button/Button.test.tsx

Step 2: README階層の設計（各コンポーネントにREADMEを配置）

各コンポーネント フォルダに、「そのコンポーネント専用の説明ファイル」を配置します。

Button/README.mdx の例:

# Button Component
 
## Overview
Primary action button for forms, dialogs, and navigation.
 
## When to Use
- Form submission
- Main action in dialogs
- Navigation
 
## When NOT to Use
- Links → use `<a>` or Next.js `<Link>`
- Toggles → use Toggle component
 
## Props
- **variant**: "primary" | "secondary" | "danger"
- **size**: "sm" | "md" | "lg"
- **disabled**: boolean
- **loading**: boolean
 
## Example
\`\`\`tsx
<Button variant="primary" size="md" onClick={handleClick}>
  Submit
</Button>
\`\`\`
 
## Accessibility
- Keyboard navigable (Tab)
- Screen reader friendly (aria-label)
- Focus visible indicator
 
## Related Components
- [Form](../Form/README.mdx)
- [Dropdown](../Dropdown/README.mdx)

Step 3: SKILL.mdの作成（目的・使い方・参照先を記述）

プロジェクトルートに SKILL.md を作成します。

# My Design System
 
> Version: 1.2.0
> Last Updated: 2026-04-09
 
## Purpose
This is the official component library for [Your Product].
 
## Quick Start
 
### Components
- [Button](./src/components/Button/README.mdx) - Primary action button
- [Form](./src/components/Form/README.mdx) - Form container
- [Card](./src/components/Card/README.mdx) - Content container
 
### Design Tokens
- [Colors](./src/tokens/colors.json)
- [Typography](./src/tokens/typography.json)
- [Spacing](./src/tokens/spacing.json)
 
## Usage Example
When you need to build a form with a submit button:
 
\`\`\`tsx
import { Form, Button } from '@mycompany/design-system';
 
export default function MyForm() {
  return (
    <Form onSubmit={handleSubmit}>
      <input type="text" placeholder="Name" />
      <Button variant="primary">Submit</Button>
    </Form>
  );
}
\`\`\`
 
## Versioning
This design system follows [Semantic Versioning](https://semver.org/).
 
## Support
For questions or contributions, see [CONTRIBUTING.md](./CONTRIBUTING.md)

Step 4: バージョン管理と自動更新の仕組み

package.json のバージョンを更新するたびに、SKILL.md が「動的に更新される」仕組みを作ります。

// scripts/generate-skill.js
const fs = require('fs');
const path = require('path');
const pkg = require('../package.json');
 
const components = fs.readdirSync(path.join(__dirname, '../src/components'))
  .filter(f => fs.statSync(path.join(__dirname, `../src/components/${f}`)).isDirectory());
 
const skillMd = `# ${pkg.name}
 
> Version: ${pkg.version}
> Last Updated: ${new Date().toISOString().split('T')[0]}
 
## Components
 
${components.map(c => `- [${c}](./src/components/${c}/README.mdx)`).join('\n')}
 
...
`;
 
fs.writeFileSync(path.join(__dirname, '../SKILL.md'), skillMd);
console.log('✅ SKILL.md generated');

package.json の scripts に追加：

{
  "scripts": {
    "build": "npm run generate-skill && tsc",
    "generate-skill": "node scripts/generate-skill.js"
  }
}

Step 5: チームへの展開とフィードバックループ

SKILL.md が完成したら、チームで試して、フィードバックを集めます。

展開方法:

1. リポジトリを GitHub に push
2. 同じ organization のチームメンバーに Share
3. Claude Code/Claude in Cowork で SKILL.md を参照させる

フィードバック ポイント:

• 「AI が正しいコンポーネントを推奨したか？」
• 「README の内容は十分だったか？」
• 「どの情報が不足していたか？」

1-2週間のフィードバック期間を経て、README や SKILL.md を改善します。

AI対応ドキュメント設計の原則

デザインシステムを「AI が読める形式」に変換する過程で、8つの原則が浮かび上がります。これらは、デザインシステムに限らず、あらゆるドキュメント設計に適用可能です。

原則 1: 階層化（Deep vs Wide）

情報を「深く掘り下げる方式」に設計します。

• Wide（現在）: 1ファイルに全情報を詰め込む → AI のコンテキスト圧迫
• Deep（理想）: SKILL.md（入口） → README.mdx（詳細） → 実装コード（最深部）

原則 2: 曖昧さの排除

「かもしれない」「多分」という表現を避けます。

❌ 「このコンポーネントはボタンのように見える」 ✅ 「このコンポーネントは <button> HTML 要素として実装されており、onClick ハンドラーをサポートします」

原則 3: メタデータの明示

バージョン、更新日時、メンテナーを必ず記載します。

原則 4: 使う/使わない の明示

「いつこのコンポーネントを使うのか」「いつ使わないのか」を列挙します。

原則 5: 実装例の充実

理想的には、各コンポーネントに3〜5つのユースケース例を記載します。

原則 6: アクセシビリティ情報の統合

ARIA ラベル、キーボード操作、スクリーンリーダー対応を記載します。

原則 7: 関連コンポーネント への参照

「このコンポーネントと組み合わせて使う」コンポーネントを記載します。

原則 8: トークン化（Design Tokens）

色・フォント・スペーシングを JSON で定義し、AI が参照可能にします。

// tokens/colors.json
{
  "primary": {
    "50": "#f0f4ff",
    "100": "#e0e9ff",
    "500": "#3b82f6",
    "900": "#1e40af"
  }
}

実装を通じて分かった課題と解決策

kintone Design System Skills を実装する過程で、複数の課題と解決策が見つかりました。

課題 1: コンテキスト量とレスポンス品質のトレードオフ

問題: README をすべて SKILL.md に含めると、AI のコンテキストウィンドウが満杯になります。

解決策: 階層設計で対応。

• SKILL.md: 1KB 以下（入口のみ）
• 各 README.mdx: 1-2KB（詳細）
• 実装コード: 参照のみ（全文読み込まない）

課題 2: チームの合意形成

問題: 「AI 向けドキュメント」という概念が新しく、チームメンバーが理解するのに時間がかかります。

解決策: 具体例を示す。 「従来: Button の使い方を手で打ってコピペ（1分）→ AI 対応後: プロンプトで自動生成（10秒）」という改善を見せると、チームの推進力が生まれます。

課題 3: 継続的な更新維持

問題: 最初は SKILL.md を更新するが、時間とともに「package.json だけ更新して SKILL.md は放置」という状態に陥る。

解決策: 自動化。

• GitHub Actions で、package.json 変更時に自動的に SKILL.md を再生成
• SKILL.md がプルリクエストに含まれるようにルール化
• CI/CD パイプラインで、SKILL.md の整合性をチェック

# .github/workflows/generate-skill.yml
name: Generate SKILL.md
 
on:
  push:
    paths:
      - 'package.json'
      - 'src/**'
 
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm run generate-skill
      - run: git add SKILL.md && git commit -m "chore: update SKILL.md"
      - run: git push

AI対応ドキュメント設計が、チーム全体の開発効率をどう変えるか

では、具体的な数字で見てみましょう。

Before: 従来のドキュメント運用

After: AI対応ドキュメント運用

差分: 2時間 → 5分。24倍の高速化です。

プロジェクトあたり 1時間55分の削減 × 100プロジェクト = 3,100時間/年の時間捻出。これは、エンジニア3-4名分の年間稼働に相当します。

更に驚くべきことに、この「AI 向けドキュメント」は 人間にとっても使いやすくなります。 なぜなら：

• 「いつ使う？」「いつ使わない？」が明確 → 正しいコンポーネント選択が容易
• 実装例が豊富 → コピペして修正するだけで完成
• バージョン情報が明示 → 「何が変わったのか」が一目瞭然

つまり、「AI のために」最適化されたドキュメントが、「人間にとっても最適」になるという相互効果が生まれるのです。

全体を振り返って：デザインシステムとAIの新しい関係

デザインシステムは、企業の UX・UI 品質を決める基盤です。しかし多くの企業が「作ったが、使われていない」という課題に直面しています。

その根本原因は、ドキュメントが「人間向け」に最適化されているからです。

では、「AI が読める形式」に変換したら？

• AI が自動的に最適なコンポーネントを選択・提案
• 新規プロジェクトの立ち上げが24倍高速化
• 人間にとっても、ドキュメントが使いやすく進化
• チーム全体の開発効率が劇的に向上

kintone Design System Skills の実装から学べることは、単なる「デザインシステムの AI 活用」ではなく、「ドキュメント設計の新しいパラダイム」 です。

今日から始められるアクション:

1. あなたのデザインシステムに SKILL.md を追加
2. 各コンポーネント フォルダに README.mdx を配置
3. Claude Code で SKILL.md を参照させてみる
4. 開発スピードの変化を測定

デザインシステムと AI の新しい関係は、すでに始まっています。