name: vis description: 会話で扱った内容や指定されたテーマを、図中心のHTML1枚にまとめて tmp/visual/ に出力する。複雑な話を可視化して掴みやすくするために使う。「vis」「図にして」「可視化して」「HTMLにまとめて」と指示されたとき。 argument-hint: '[可視化するテーマ。省略時はここまでの会話] [--details で厚く書く]' disable-model-invocation: true
Vis
会話で扱った内容、または引数で指定されたテーマを、図中心のHTML1枚にして tmp/visual/ に書き出すスキル。縦スクロールで読む解説資料を作る。
目的は、人間の認知負荷を減らすこと
この文書の数値規約はすべて、その目的の代理指標でしかない。節数も段落数も、それ自体に価値はない。
[!IMPORTANT] （AI・必須） 数値規約を全部満たしていても、読んで分からない資料は失敗である。最後の検査（「図だけを見て要点を言えるか」）を必ず通すこと。
手順
上から順に実行する。
- 対象と厚さを決める：引数があればそれを、無ければこれまでの会話をもとにする。会話が対象のときは、どこからどこまでを扱うかも決める。引数に
--detailsがあれば厚く書き、無ければ既定の薄さで書く（後述の規約）。 - 見出し構成を承認してもらう：タイトル・各節の見出し・各節で何を図にするかを、箇条書きで短く提示する。良しと言われるまでHTMLを書き始めない。 確認はこの1回だけで、以降は最後まで自律で進める。
- 雛形をコピーして書く：
.claude/skills/vis/assets/template.htmlを出力先へコピーし、中身を差し替える。図は.claude/skills/vis/references/figure-patterns.mdの骨格を土台にする。 - 描画を確かめて直す：後述の手順でブラウザに描画させ、崩れを直す。
- 図だけで要点を言えるか確かめる：後述の最終検査を通す。
- 渡す：
SendUserFileでdisplay: "render"を指定して送る。パスを伝えるだけにしない。
出力先
| 項目 | 決まり |
| ------------ | ------------------------------------------------------------------------------ |
| ディレクトリ | tmp/visual/（無ければ作る。git 管理外） |
| ファイル名 | YYYYMMDD-<題名のケバブケース>.html（例：20260817-vis-skill.html） |
| 日付 | date +%Y%m%d で取る |
| 既存ファイル | 上書きしない。同名なら末尾に -2 を足し、それも在れば空いている番号まで増やす |
後から読み返したり、他人に見せたりする使い方をするので、過去の分を消さない。
書くときの規約
| 項目 | 規約 | 外れたときの直し方 |
| ---------------- | ------------------------------------------------------------------- | ------------------------------ |
| 節の数 | 既定は2〜3。--details 指定時は3〜8 | 統合するか、資料を分ける |
| 1節の本文 | 既定は1〜2段落、--details 指定時は3段落以内。どちらも1段落2文以内 | 削るか、節を割るかの2択 |
| 図のある節 | 全節の半分以上 | 図にできる切り口で節を割り直す |
| 図にするかの判定 | 箇条書きに戻しても構造が掴める内容なら、図にせず表か箇条書きにする | —— |
| 図の描き方 | 手書きの inline SVG のみ | —— |
| 見た目 | 雛形のCSSは変えない | —— |
既定を薄くするのは、書く量がそのまま待ち時間になるからである。実測では、5節の資料1本を作った376秒のうち275秒（73%）が執筆で、ブラウザで描画を確かめる工程は76秒（20%）だった。節を減らせば、その73%がほぼ比例して減る。
[!IMPORTANT] （AI・必須） 本文が上限の段落数に収まらないときに、理由を書いて超えてはならない。収まらないのは「冗長」か「1節に2つ以上の話を詰めている」かのどちらかなので、削るか節を割るかしか選べない。理由を書けば超えられる形にすると、書き手であるAI自身が毎回それを許してしまう。
Mermaid は使わない。外部のライブラリを読まずに図が出るようにするためで、この資料はネットの無い環境でもそのまま開ける必要がある。したがって /design-doc-mermaid は呼ばない。
描画を確かめて直す
崩れは書いた文字列を見ても分からないので、必ず実際に描画させる。
mcp__Claude_Browser__resize_windowをwidth: 900, height: 3000で呼ぶ。1枚に入る量が増え、撮る枚数が減るmcp__Claude_Browser__preview_startにfile:///<出力ファイルの絶対パス>を渡すmcp__Claude_Browser__computerのscreenshotで見る。入りきらなければ下へscrollして続きを撮る。戻って撮り直さない（同じ場所を往復すると枚数だけが増える）- 縮小されて細部が読めず、崩れが疑わしい節だけ、
resize_windowをwidth: 900, height: 900にして撮り直す - 下の崩れを直す
- 直したら
preview_startを呼び直す。表示は読み込んだ時点のスナップショットなので、直しただけでは反映されない。直しが無ければ呼び直さない
| 崩れ | 直し方 |
| ---------------------------- | ------------------------------------------ |
| 文字が箱からはみ出す | 言葉を短くする（フォントを小さくしない） |
| 線と文字が重なる | 線をずらすか、ラベルの位置を動かす |
| 矢印の先が箱に刺さっていない | path の終点座標を箱の縁に合わせる |
| 文字が読めない（黒地に黒） | 雛形の body の背景色を消していないか見る |
ブラウザのツールが使えない環境では、崩れを見ていない旨を明記して渡す。黙って飛ばすと、崩れた資料が検査済みとして渡る。
最終検査
[!IMPORTANT] （AI・必須） 完了を報告する前に、スクリーンショットを見ながら次を確かめ、すべて「はい」になるまで直すこと。
- 本文を読まず、図と見出しだけで各節の要点を言えるか。言えない節は、図が本文の飾りになっているので図を描き直す
- 図のある節が、全節の半分以上あるか
- 節の数と本文の段落数が、「書くときの規約」の上限に収まっているか（
--detailsの有無で上限が変わる）- 崩れが残っていないか
- 雛形の
{{ }}が1つも残っていないか（grep -c '{{' <出力ファイル>が 0 になるか）。<head>の<title>は画面に出ないので目視では気づけない
最初の1つが本体である。以降は、それを満たしやすくするための数値と手当てでしかない。
使用方法
/vis # ここまでの会話を2〜3節の薄い資料にする
/vis リトライ設計の選択肢 # 指定したテーマで薄い資料を作る
/vis リトライ設計の選択肢 --details # 節も本文も増やして厚く書く
まず薄いものを受け取り、足りなければ --details で作り直す方が、厚いものを待つより速く要点に届く。
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Create a DESIGN.md
Documentation
Generate a complete DESIGN.md file for any website or app to document design systems in a format AI agents can read.