agentleFS
yktsnetyktsnet/dotfiles-public/.claude/skills/mermaid-diagram/SKILL.md

mermaid-diagram

Skill1 starsChanged 6 days agoMITView on GitHub

GitHub 上でレンダリングされる Mermaid 図を新規作成・監査・修正する。README の構成図・技術記事の図・解説ドキュメントの図を描きたいとき、既存の図が横に長くて読みにくい・何を図にすべきか決まらないときに使う。図を SVG に焼かず ```mermaid フェンスのまま扱う。

14 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use deepxiv, figure-description and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • raja21068Skill

    deepxiv

    Search and progressively read open-access academic papers through DeepXiv. Use when the user wants layered paper access, section-level reading, trending papers, or DeepXiv-backed literature retrieval.

    Also in 4 projects that use this

  • raja21068Skill

    figure-description

    Process user-provided patent figures and generate formal drawing descriptions. Use when user says \"附图处理\", \"figure description\", \"附图说明\", \"drawings description\", or wants to describe patent figures with reference numerals.

    Also in 5 projects that use this

  • +10 more from raja21068

The file

Files
SKILL.md

mermaid-diagram

Mermaid 図の基準と手順を持つ。目的はきれいな図を描くことではなく、その図が無いと伝わらないものだけを、読める大きさで描くこと。

前提は、GitHub が ```mermaid フェンスを本文カラム幅(約 768px)に縮小して描画すること。図を SVG に焼かずフェンスのままコミットする(テーマ追従と差分閲覧ができなくなるため)。したがって図の幅はそのまま文字サイズになる。

README の Architecture 節からは repo-ship Skill の readme 段が本 Skill を呼ぶ。単体でも使える。

1. 基準

描くか、描かないか

分岐・失敗経路・境界をまたぐグループ化・対比のどれも無いなら、図にしない。 順番に起きるだけの処理は番号付きリストの方が速く読める。

主題図でしか表せない理由
分岐条件で処理が割れて、また合流する。文章では分岐の先を読み終えるまで全体が見えない
失敗経路リトライループ・複数の終了状態。制御フローは線形の文章に写せない
境界デバイス・ネットワーク・信頼境界をまたぐ配置。subgraph でしか表せない
対比before / after、あるべき姿と現状。並置そのものが主張になる

「全体像」は主題ではない。 描くと分岐の無い一直線か、抽象度の混ざった図になる。全体像が要るならディレクトリ構成表かコンポーネント表で出す。

図を落とすときは中身に合った形へ置き換える(図をやめることと情報を捨てることは別)。

図の中身置換先
順番に起きる処理の列挙番号付きリスト
名前と役割・段の対応表
1ステップだけの変換一文

描くと決めたら、そのリポで一番おもしろい判断が1ノードに潰れていないかを見る。潰れているなら主題が間違っている。そのノードを展開したものを描き、周辺のパイプラインは本文に落とす。

幅 — 縦は無料、横は有料

規則理由
TD を既定にする。LR はチェーンが4ノード以下のときだけLR の幅 ∝ チェーン長、TD の幅 ∝ 分岐本数
エッジラベルは最短。API 列挙・引数・条件式を載せないノードを増やさず幅だけ増やす
ノードラベルは絵文字を含めて全角12文字程度まで。詳細は図の下の本文へ長いラベルはランク全体の幅を押し広げる
横並びの subgraph は2つまで。3つ以上なら TD で縦に積むsubgraph は枠とパディングぶんの幅を食う

しきい値は運用で調整してよい。動かさないのは「幅が文字サイズである」という前提の方。

幅はレンダリングせずに見積もる。最長ランクのノード数 × その行のラベル長 + エッジラベル長の合計が目安(LR なら最長ランク=チェーン全体、TD なら最も広い分岐の段)。削る順序は エッジラベル → ノードラベル → 向きの変更 → 図の分割。

形と線種に情報を載せる

形と線種は幅を増やさずに情報の次元を1つ足す。全部同じ四角・同じ矢印の図はこの余地を捨てている。

記法型
([ ])アクター(人・外部の呼び出し元)
{{ }}サービス・変換器
[( )]データストア
{ }判断・分岐点
[/ /]外部からの投入・ファイル
[ ]それ以外の処理
記法意味
--> 実線ローカル・同一プロセス内
-.-> 点線ネットワーク越し・非同期
==> 太線人間の物理操作・主経路

割り当ては固定ではないが、形・線種・絵文字は1つの図の中では必ず一貫させる。

記法: 改行は \n ではなく <br/>。ラベルに記号を含むときは ["..."] で引用する。

ノードの絵文字

ノードラベルの先頭に絵文字を1つ置くことを既定にする。 形がノードの型を示すのに対し、絵文字はノードの中身を示す。ラベルを読む前に中身の見当がつき、矢印を目で追うときの目印にもなる。

flowchart TD
    Cat(["🐱 Feeding Shelf"]) ==> Switch["🔌 Reed Switch"]
    subgraph Server["VPS"]
        API["🌐 FastAPI"] --> DB[("🗄️ PostgreSQL")]
    end
    Switch -.-> API
規則理由
1ノードに1つ、ラベルの先頭に置く2つ以上並べると目印にならない
subgraph の見出しとエッジラベルには付けない見出しは枠で、エッジは線種で区別がつく

当てはまる絵文字が無いノードは無理に付けずにラベルだけにしてよい。

抽象度を混ぜない

概念(ルート・フェーズ・レイヤー)と実体(プロセス・ファイル・サービス)を同じ平面に置かない。 概念名の subgraph の外に具体的なミドルウェアを並べる形になったら、subgraph を捨てて構造(合流・分岐)に語らせる。

分けるか、まとめるか

1図=1主題。 分けるかどうかは主題の数で決まり、図の大きさでは決まらない。分けてよい軸は3つに限る。

軸例
時間ビルド時 / 実行時、セットアップ / 定常運用
正常系 / 異常系主経路 / 停止・リトライ・強制終了の経路
before / after移行前 / 移行後

まとめる前に、片方が単独で主題を持つかを見る。持たない図はまとめる対象ではなく消す対象。分けたら各図に主題を示す見出しか一文を付け、図をまたぐ同じノードはラベルを一致させ、分割の軸を本文で明示する(「以下は正常系。停止経路は次の図」)。

2. 手順

入力モード
図がまだ無い新規
既存の図がある(読みにくい・直したい・棚卸し)監査

新規

  1. 箇条書きで書く。 足りるなら図を作らず、置換先の形に納める。大半がここで落ちる。この手順を飛ばさない
  2. 主題を1つ決める。 2つ以上なら分割の3軸に当たるかを見て、図ごとに主題を示す一文を付ける
  3. 対象を読む。 分岐条件・終了状態・デプロイ先を推測で書かない(図は既にあるものの写像)
  4. 向き・形・線種・絵文字を決める
  5. 幅を数える
  6. 図の下に本文を置く。 ラベルから削った詳細をここへ落とす。図と本文で同じことを二度書かない

監査

ファイルに2枚以上あるなら、先にファイル全体で見る。

[ ] 各図が単独で主題を持っている(持たない図は削除対象。先に落とす)
[ ] 分かれている軸が3つ(時間 / 正常系・異常系 / before・after)のいずれか
[ ] 各図に主題を示す見出しか一文がある
[ ] 1枚に主題が2つ以上詰まっていない(「大きいから割る」ではなく「主題が2つだから割る」)

そのうえで1ブロックずつ見る。

[ ] 主題がある(無い一直線のパイプラインなら、削除して箇条書きへの置換を提案する)
[ ] 一番おもしろい判断が1ノードに潰れていない
[ ] LR なら チェーン4ノード以下
[ ] エッジラベルに API 列挙・引数・条件式が無い
[ ] ノードラベルが絵文字を含めて全角12文字程度に収まっている
[ ] 当てはまる絵文字があるノードは、ラベルの先頭に絵文字がある
[ ] 横並び subgraph が2つ以下
[ ] 形状・線種・絵文字が図の中で一貫している
[ ] 抽象度が混ざっていない
[ ] 改行が <br/>

指摘して終わりにせず、修正後の Mermaid をその場で書く。主題ごと差し替える提案は幅の調整ではなく描く対象の変更なので、なぜ今の主題が成立していないかを1〜2文で添える。

3. 検証

Mermaid のレンダリングはローカルで確認できない。SVG に焼いて確認しようとしない。

  • 構文: ノード ID の重複・引用符の閉じ忘れ・subgraph の end 抜けを目視で確かめる
  • 幅: 上の数え方で見積もる。実測は user に委ねる
  • 見た目の確認が要るなら、GitHub 上での表示確認を ## 検証手順 に書いて user に渡す

4. 注意

  • Issue ドリブン期のリポの README を直す場合、相談者は実装しない。local-issue Skill で Issue を立てるまで(軽量経路の条件を満たす場合を除く)
  • 図に固有の接続情報(ドメイン実値・Tunnel UUID・VPN の IP 等)を書かない。secrets-agents/ の <PLACEHOLDER> 方針に従う
  • 図を画像化する必要が出ても、外部ホスティングに依存させない

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.