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 で作り直す方が、厚いものを待つより速く要点に届く。
Generateur de Documentation API
Documentation
Genere automatiquement de la documentation API OpenAPI/Swagger.
Rédacteur Technique
Documentation
Rédige de la documentation technique claire selon les meilleurs style guides.
Créer un DESIGN.md
Documentation
Générez un fichier DESIGN.md complet pour tout site ou application afin de documenter les systèmes de conception dans un format lisible par les agents IA.