オリジナルSkillsの作り方：覚書

.agent/skills/
├── dashboard-design-principles/
│   ├── SKILL.md
│   └── references/
│       └── guidebook-notes.md
└── dashboard-html-implementation/
    └── SKILL.md

まず、dashboard-design-principles/SKILL.md です。

---
name: dashboard-design-principles
description: ダッシュボードの設計、KPIの見せ方、チャート選定、情報の優先順位づけ、見やすいレイアウト設計、提示型ダッシュボードの改善を行うときに使う。Use this skill when designing dashboards, choosing chart types, structuring KPI views, improving readability, prioritizing information, or reviewing presentation-oriented dashboards for decision-making.
---

# Dashboard Design Principles

## Goal
見る人が状況をすばやく把握し、必要な判断や次の行動につなげられる、わかりやすいダッシュボードを設計する。

このスキルは、主に提示型ダッシュボードを対象とする。
探索型の高度な分析UIや、データ基盤そのものの設計は主対象ではない。

## Scope
このスキルが扱う範囲:
- ダッシュボードの目的整理
- 見る人の整理
- 伝えるべき情報の選定
- チャート種別の選定
- レイアウト方針
- 見出し、注記、比較軸の整理
- 誤解を生みにくい表現への改善
- プロトタイプ案の作成支援
- 実装前レビュー

このスキルが主に扱わない範囲:
- データ収集基盤の設計
- ETLやDWHの詳細設計
- データクレンジング
- 高度な統計分析
- 探索型ダッシュボードの複雑なインタラクション設計

## Working Mode
ユーザーから具体的な実装指示がない場合、次の順序で考えること。

1. 要件を整理する
2. 必要な情報を一覧化する
3. プロトタイプ方針を決める
4. 表現方法を選ぶ
5. 実装に渡せる粒度まで整理する

## Instructions

### 1. まず目的を明確にする
最初に、次の観点を短く整理する。
- 誰が見るのか
- どの場面で見るのか
- 見たあと何を判断・行動するのか
- 何を最優先で伝えるのか
- 更新頻度はどの程度か
- どの制約があるか（画面サイズ、時間、利用環境、データ欠損など）

目的が曖昧なら、いきなりチャートを選ばず、先に目的と利用場面を言語化する。

### 2. 提示型か探索型かを判定する
次のように考える。
- 現状把握、異常検知、会議用、報告用、意思決定補助が中心なら提示型
- 深掘り分析、仮説探索、複雑な切り分け、分析担当者向けなら探索型

原則として、このスキルでは提示型を優先する。
探索型の要件が強い場合は、その旨を明示し、提示型の範囲でまず整理できる部分を切り出す。

### 3. 載せる情報を絞る
必要な情報を列挙したうえで、次の観点で絞る。
- 判断に本当に必要か
- 一画面で理解できるか
- 似た意味の情報が重複していないか
- 詳細より概況を優先すべきか

情報が多すぎる場合は、全部載せずに優先順位をつける。
最重要情報、補足情報、詳細情報に分けて整理する。

### 4. チャートを目的から選ぶ
チャートは見た目ではなく、伝えたい内容から選ぶ。

基本方針:
- 単一の重要数値を見せたい -> KPIカード
- 時系列の推移を見せたい -> 折れ線
- 項目間の大小比較を見せたい -> 棒グラフ / 横棒グラフ
- 構成比を見せたい -> 構成比表現を検討するが、正確な比較が必要なら棒系を優先
- 増減や差分を見せたい -> 差分が読み取りやすい比較表現
- 地域差を見せたい -> 地図は必要性がある場合のみ使う

チャート選定時は必ず、
「この表現で見る人は何をすぐ理解できるか」
を一文で説明できるようにする。

### 5. レイアウトは視線と優先順位で決める
配置は次の順序を基本とする。
- 最上部: 全体の状況を示す最重要KPI
- 次: 重要な比較や推移
- 下部: 補足情報や内訳
- 端や下段: 注釈、定義、補助情報

同じ種類の情報は近くに置く。
比較して見せたいものは、離しすぎない。
整列、余白、見出し階層をそろえる。

### 6. タイトルとラベルで誤解を防ぐ
各要素には、必要に応じて次を明示する。
- 指標名
- 単位
- 対象範囲
- 期間
- 比較対象
- 更新日や基準日
- 注意事項

タイトルは抽象語で済ませず、
何の数値か、どの範囲か、どの期間か
が分かるようにする。

悪い例:
- 売上推移
- 利用状況
- 件数比較

良い例:
- 2026年度 月次売上推移
- 直近30日間のアクティブ利用者数
- 部門別問い合わせ件数の比較

### 7. 見る人が知りたいことを優先する
制作者の都合ではなく、見る人の疑問に答える構成を優先する。
次のような問いを想定して整理する。
- 今どうなっているのか
- 以前と比べてどうか
- 目標や基準と比べてどうか
- 異常かどうか
- 次に何を見るべきか

### 8. 誤解を生みにくい表現を選ぶ
次を常に確認する。
- 強調が過剰でないか
- 比較の前提が揃っているか
- 軸や単位が曖昧でないか
- 色だけに依存していないか
- 小さすぎる文字や読みにくい凡例になっていないか
- 装飾が意味理解を邪魔していないか

### 9. アクセシビリティを意識する
最低限、次を守る。
- 色だけで区別しない
- 文字サイズを小さくしすぎない
- コントラスト不足を避ける
- ラベルや見出しを省略しすぎない
- 重要情報は注記なしでも読めるようにする

### 10. まずプロトタイプで合意を取る
実装前に、低コストで構成案を確認する。
次の順で進める。
- 必要情報の一覧化
- ざっくりした配置案
- ヒアリング
- フィードバック反映
- 実装へ移行

いきなり完成形を作らず、まず意思決定に必要な骨格が合っているかを見る。

## Output Format
ユーザーがダッシュボード作成を依頼したら、基本的に次の順で出力する。

1. 目的整理
2. 想定閲覧者
3. 提示型 / 探索型の判定
4. 掲載情報の優先順位
5. 推奨レイアウト案
6. 推奨チャート案
7. 表現上の注意点
8. 実装前に確認すべき点

必要なら次の形式で簡潔にまとめる。

### Design Brief
- 目的:
- 閲覧者:
- 利用場面:
- 最重要メッセージ:
- 判定: 提示型 / 探索型

### Proposed Structure
- 上段:
- 中段:
- 下段:
- 補足:

### Chart Choices
- 指標A -> 理由:
- 指標B -> 理由:
- 指標C -> 理由:

### Risks / Notes
- 誤解リスク:
- 欠損データ時の扱い:
- 定義明記が必要な指標:

## Review Checklist
提案の最後に、必要に応じて次を自己点検する。
- 目的が先に定義されているか
- 見る人が明確か
- 提示型として過不足ないか
- 情報量が多すぎないか
- 各チャートに明確な役割があるか
- 期間、単位、比較対象が明確か
- 誤解を招く表現がないか
- 色や装飾に頼りすぎていないか
- 実装前に合意が取れる形になっているか

## Constraints
- 目的が曖昧なままチャートを決めない
- 情報を無制限に追加しない
- 装飾目的の可視化をしない
- 色だけで意味を伝えない
- 探索型の複雑なUIを、提示型案件に持ち込まない
- データ準備やクレンジングを、このスキルの責務として扱わない
- 実装ツール固有の細かい設定を、このスキルに混ぜ込まない

## Example 1
User:
営業会議向けに、月次売上と問い合わせ状況がすぐ分かるダッシュボードを作りたい

Assistant:
- 目的: 会議で現状と変化を短時間で共有し、対応判断につなげる
- 閲覧者: 営業責任者、部門長
- 判定: 提示型
- 最重要情報:
  - 月次売上の推移
  - 目標比
  - 問い合わせ件数の推移
  - 問い合わせ種別の内訳
- 推奨構成:
  - 上段: KPIカード（今月売上、目標比、問い合わせ件数）
  - 中段: 月次売上推移、問い合わせ推移
  - 下段: 問い合わせ種別比較、注記
- 注意点:
  - 単位と対象期間を明記
  - 目標比は基準値を併記
  - 内訳は色に頼りすぎない

## Example 2
User:
分析担当者が地域別の差分を深掘りできるダッシュボードを作りたい

Assistant:
- 判定: 探索型の要件が強い
- このスキルでは、まず提示型として共通認識を持つための上位サマリー画面を先に整理する
- その上で、詳細分析用の探索機能は別レイヤーとして扱う
- まず作るべき画面:
  - 全体サマリー
  - 地域別の主要指標比較
  - 異常値の一覧
- 追加で必要:
  - 深掘り用フィルタ設計
  - 詳細分析の操作要件整理

次が、dashboard-design-principles/references/guidebook-notes.md です。デジタル庁のガイドは、見る人の意思決定や行動につながる情報表現、Do’s / Don’ts、要件整理とプロトタイピングを含む構成なので、その要点だけを参照メモ化しています。 (デジタル庁)

# Guidebook Notes

## Purpose
ダッシュボードは、関係者の正しい共通認識をつくり、意思決定の質を上げ、次の行動につなげるために設計する。

## Core Process
- 要件を整理する
- プロトタイプで合意形成する
- わかりやすい情報表現で実装する

## Core Ideas
- ダッシュボードは、見る人・利用場面・次の行動で設計が変わる
- 主な類型は提示型と探索型
- まず提示型を優先して整理する
- 作成の流れは、要件整理、プロトタイピング、実装
- 可視化のわかりやすさと誤解の少なさを重視する
- データ準備やクレンジングは別工程

## Design Reminders
- 見る人が知りたいことを優先する
- 誤解を生みにくい表現を選ぶ
- 過剰な装飾を避ける
- 単位、期間、比較軸を明確にする
- 色だけに意味を持たせない
- ダッシュボードはまず提示型を意識する

## Scope Boundary
この知識は主に可視化設計のためのもの。
データ整備、ETL、分析基盤の設計までは直接扱わない。

最後に、dashboard-html-implementation/SKILL.md 。
これは設計原則を受けて、HTML/CSS/JavaScript に落とす役目です。Antigravity の codelab でも、SKILL.md 本体に Goal、Instructions、Examples、Constraints を持たせる構成が推奨されています。

---
name: dashboard-html-implementation
description: HTML、CSS、JavaScript でダッシュボード画面を実装するときに使う。Use this skill when the user asks to build a dashboard page, KPI dashboard UI, responsive analytics screen, management report page, or chart-based HTML prototype using HTML/CSS/JavaScript.
---

# Dashboard HTML Implementation

## Goal
提示型ダッシュボードの設計意図を崩さずに、HTML/CSS/JavaScript で見やすく実装する。

このスキルは実装担当。
ダッシュボードの目的整理やチャート選定の原則は `dashboard-design-principles` を優先する。

## Working Rule
実装前に、次を短く確認する。
- 誰が見る画面か
- 何を最優先で把握させるか
- どの指標を表示するか
- どのチャートを使うか
- 1画面完結か、複数セクションか

目的が曖昧なら、勝手に派手なUIを作らず、提示型ダッシュボードとして最小構成でまとめる。

## Implementation Principles

### 1. 画面構成
基本構成は次を優先する。
1. ヘッダー
2. サマリーKPI
3. 主要な推移または比較チャート
4. 補足の内訳
5. 注記または更新情報

### 2. レイアウト
- デスクトップでは横並びを使ってもよいが、情報の優先順位を崩さない
- モバイルでは縦積みにする
- 同系統の情報は近くに置く
- 余白で区切り、罫線や装飾で区切りすぎない
- 1セクション1役割を守る

### 3. KPIカード
KPIカードには必要に応じて次を含める。
- 指標名
- 値
- 単位
- 比較情報（前月比、前年同月比、目標比など）
- 補足ラベル

KPIカードを装飾しすぎない。
最重要KPIだけを適度に強調する。

### 4. チャート実装
- 時系列 -> line
- 比較 -> bar
- 内訳 -> 必要性が高いときのみ pie/doughnut を検討
- 正確な比較が必要なら pie より bar を優先
- 軸ラベル、単位、期間、凡例を省略しすぎない

### 5. 色と視認性
- 色数を増やしすぎない
- 強調色は本当に重要な系列だけに使う
- 色だけで意味を伝えない
- 背景は落ち着かせ、数値やラベルを主役にする
- コントラスト不足を避ける

### 6. テキスト
見出しは曖昧にしない。
悪い例:
- 売上
- 状況
- 利用
良い例:
- 2026年度 月次売上推移
- 直近30日間の問い合わせ件数
- 商品カテゴリ別 売上構成

### 7. レスポンシブ
- スマホでは横スクロール前提にしない
- 複雑な表は簡略化する
- グリッドは2〜3列までに抑える
- チャート高さは固定しすぎない

### 8. JavaScript
ユーザーが静的モックを求めている場合は、ダミーデータでよい。
実データ連携がない場合は、コード内に仮データを明示する。
ライブラリ指定がなければ、シンプルな実装を優先する。

## Output Rules
ユーザーが実装を求めたら、次の順で返す。
1. 実装方針の短い整理
2. 生成するファイルの説明
3. 完成コード
4. 必要なら差し替え箇所の説明

## Constraints
- チャート種別を見た目の好みだけで決めない
- ダッシュボードを広告LPのように装飾しない
- グラデーションや影を多用しない
- 情報量を増やしすぎない
- ラベルや単位を省略しない
- 実装都合で設計意図をねじ曲げない

## Default Tech Choice
ユーザー指定がなければ次を優先する。
- 単一HTMLファイル
- 内部CSS
- 最小限のJavaScript
- 必要時のみ Chart.js

## Example
User:
営業会議向けのダッシュボードをHTMLで作って。上にKPI、下に売上推移と問い合わせ件数を見せたい。

Assistant:
- これは提示型ダッシュボード
- 上段に KPIカード3枚
- 中段に売上推移の折れ線
- 下段に問い合わせ件数の棒グラフ
- 注記として期間と更新日を表示
- 1ファイルのHTMLで実装する

これで一式です。