コーディング・エージェント Cline の Skills で Mermaid ダイアグラムを生成する

はじめに

以前、コーディングエージェント Cline の Skills 機能を使って、Oracle Database の AWR レポートを生成・分析する Skill を作り、Skills のコンテキスト節約効果を確認する記事を書きました。

今回は、自然言語の指示から Mermaid ダイアグラムを生成して画像ファイルとして出力する Skill を作ってみましたので、そのご紹介です。

Cline の Skills とは

Skills は、Cline（VS Code 上で動作する OSS のコーディング AI エージェント）に実装されている機能で、特定のタスクを実行するための専門知識やワークフローを SKILL.md というファイルにまとめて定義しておく仕組みです。

Skills の重要な特徴はプログレッシブ・ローディング（段階的読み込み）です。スキルが登録されていても、通常は YAML フロントマターの name と description だけがコンテキストに載っていて、実際にそのスキルが必要と判断されたときにだけ SKILL.md の本文が読み込まれます。ですので、多数のスキルを登録してもコンテキストウィンドウが圧迫されません。前回の AWR レポートの記事では、このコンテキスト節約効果を実際のトークン消費量で確認しました。

Skills の詳細については Cline の公式ドキュメントをご参照ください。

なぜ Mermaid の Skill を作ったのか

LLM は Mermaid スクリプトを普通に生成できます。VS Code にも Mermaid をプレビュー表示する拡張機能があります。それなのになぜわざわざ Skill を作ったのかというと、いくつか微妙に不便なところがあるからです。

まず、LLM が生成する Mermaid スクリプトにはときどき構文エラーが含まれていてレンダリングに失敗することがあります。特に Mermaid スクリプトを画像にレンダリングする CLI として、 mmdc を使う場合に、シーケンス図で<br> や波括弧、シングルクォートなどを使ってしまうとパースエラーとなることがあります。また、フローチャートで ノードラベルに end を小文字のまま使ってしまうケースは割とよく見かけます。Skill にガイドラインを書いておけば、こうした「よくある間違い」をエージェントが事前に回避できます。

次に、VS Code の Mermaid プレビュー拡張は図の確認には便利ですが、生成した図を画像として保存する際に制約があったりして一手間かかることがあります。Skill では mmdc（mermaid-cli）を使って直接 PNG や SVG に変換するので、画像ファイルがそのまま得られます。

それから、シーケンス図の見やすさの問題もあります。Claude Desktop のような環境ではフェーズごとに背景色を変えて色分けしてくれたりしますが、素の LLM に Mermaid スクリプトを書かせるとそこまでは気が回らないことが多いです。この Skill では rect と Note over を組み合わせたグルーピングパターンや推奨カラーパレットを定義しているので、見た目にもわかりやすい図が出力されます。

Skill の概要

この mermaid-skill は、以下のように動作します。

1. ユーザーが「○○のシーケンス図を描いて」「このシステムのアーキテクチャをフローチャートにして」のように自然言語で指示する
2. Cline がスキルの description を見て、この Skill を読み込む
3. SKILL.md に記載されたガイドラインに従って Mermaid スクリプトを生成し、.mmd ファイルとして保存する
4. npx @mermaid-js/mermaid-cli で画像にレンダリングする
5. Windows の場合は start コマンドで生成された画像を自動表示する

レンダリングには npx 経由で @mermaid-js/mermaid-cli を起動するので、事前にグローバルインストールしておく必要はありません。npx が実行時に一時的にパッケージをダウンロードして、使い終わったら削除してくれます。

デフォルトの出力形式は PNG ですが、SVG が欲しいときは「SVGで出力して」とお願いすれば対応してくれるはずです。

SKILL.md の中身

SKILL.md の全文は本記事末尾に掲載しますが、構成の概要を説明します。

YAML フロントマター

---
name: mermaid-skill
description: 自然言語の説明からMermaidダイアグラムを生成するスキル。フローチャート、シーケンス図、ER図などの作成時に使用。システム設計、アーキテクチャ可視化、プロセスフロー説明、データモデル設計などのタスクで有効。
---

description がスキル発動の判断材料になります。ユーザーの指示がこの説明に合致すると Cline が判断したときに SKILL.md の本文が読み込まれます。

手順の定義

ユーザーの指示を理解してから、図のタイプを選択し、スクリプトを生成して、ファイルに保存し、mmdc でレンダリングして、結果を出力するまでの一連の手順を定義しています。

レンダリングコマンド

npx @mermaid-js/mermaid-cli -i <入力ファイル.mmd> -o <出力ファイル.png> --width 4096 --height 4096

解像度は 4096x4096 にしています。大きめの図でもつぶれずに読めるようにするためです。

Mermaid 図生成ガイドライン

SKILL.md の後半は、LLM が Mermaid スクリプトを生成する際の注意事項をまとめたガイドラインです。これが、この Skill の肝の部分です。ほとんどは、Mermaid スクリプトの規約、お作法というよりも CLI の mmdc との相性かもしれません。

フローチャート、ER図、シーケンス図のそれぞれについて、LLM がよく間違えるポイントと正しい書き方を具体例付きで記載しています。たとえばフローチャートでは、ノードラベルに括弧を含むときは二重引用符で囲む必要があること、end を小文字のまま使うと図が壊れること、などです。

シーケンス図はとりわけ問題が起きやすいので、禁止文字の一覧をテーブルで整理しています。<br> や波括弧、シングルクォート、セミコロンなどは CLI 環境の mmdc でパースエラーを引き起こします。改行したいときは複数のメッセージに分割する方法を推奨しています。また、メッセージラベルにコードスニペットを書いてしまう（callMCPTool('get_doc', {docId}) のような）ケースも禁止文字に引っかかる典型的なパターンなので、自然言語で簡潔に書くよう指示しています。

ER図については、Oracle Database のカラム型との相性を考慮した注意事項を含めています。NUMBER(精度,スケール) や VECTOR(次元数, データフォーマット) のようなカンマ入りの型指定が Mermaid では通らないため、スケールやデータフォーマットを省く必要があることを記載しています。

さらに、スクリプト生成前のセルフチェックリストと、パースエラーが発生した場合のリカバリ手順も定義しています。

なお、フローチャート、ER図、シーケンス図以外の図（状態遷移図やガントチャートなど）についてはガイドラインに含めていません。今後、必要に応じて追加していくつもりです。

Mermaid でシーケンス図を生成したみた

以前、超優秀な若手同僚から紹介された記事を読んでいて記事中の疑似コードの理解に苦労していたときに、使てみました。

読んでいた記事はこちらです。

なお、LLM は、OCI 生成AIサービス（Generative AI Service）の grok-4-fast-reasoning を openai-compatible API で使用しました。

Cline でOCI 生成AIサービス（Generative AI Service）の xAI モデルを利用するには、OSS の LiteLLM Proxy を経由する形態と、OCI 生成AIサービスの OCI Generative AI API keys と Cline の openai-compatible API Provider を使う形態があります。LiteLLM Proxy を経由すると、Cline は、その LLM が Function Calling を native にはサポートしていないとみなして、Cline 独自の XML タグに基づくツール起動方式を使用します。一方で、openai-compatible を使う場合は、native の Function Calling を使います。一般的には、native の Function Calling の方が精度が良いと言われています。ただし、逆であることもあるので両方を試して方式を決定することをおすすめします。

Cline に渡したプロンプト

https://www.anthropic.com/engineering/code-execution-with-mcp の記事を読んで、
Benefits of code execution with MCP のセクションに書かれている
プログラムコードの動作をシーケンス図にしてください。

Cline が立てた Plan

Cline のタスク完了時のメッセージ

生成された Mermaid スクリプト

output\mcp_sequence.mmd

sequenceDiagram
    participant Dev as Developer
    participant Agent as Agent LLM
    participant CodeExec as Code Execution Env
    participant MCPClient as MCP Client
    participant Tool as MCP Tool

    rect rgb(200, 230, 200)
        Note over Dev, Agent: Preparation Phase
        Dev->>Agent: Setup MCP client
    end

    rect rgb(200, 200, 230)
        Note over Agent, Tool: Execution Phase
        Agent->>CodeExec: Write code to call tools
        CodeExec->>MCPClient: Execute code
        MCPClient->>Tool: Invoke tool
        Tool-->>MCPClient: Return result
        MCPClient-->>CodeExec: Pass result
        CodeExec-->>Agent: Return to agent
    end

生成されたシーケンス図

微調整してみる

シーケンス図のラベルが英語で生成されてしまったので日本語に変えてもらいます。
「ラベルは日本語にして、mmd ファイルと png ファイルの名前に _jp と付けて再生成して」とお願いしてみました。
生成された日本語版はこちらです。

DB 接続との組み合わせ

SQLcl MCP サーバーなどでデータベースに接続しておけば、スキーマ内のテーブル群の ER 図を生成することもできます。「このスキーマの ER 図を描いて」と指示すれば、エージェントが MCP サーバー経由でテーブル定義を取得して Mermaid の erDiagram スクリプトを生成し、画像にレンダリングしてくれます。

Oracle SQL Developer の拡張機能でも ER 図は表示できますが、画像ファイルとして保存できること、日本語の自然言語で「このテーブルと依存関係にあるテーブル群だけ描いて」のように微調整の指示を出せることは、この Skill ならではの利点です。

おまけ

ちょっと面白いのは、図を生成してとお願いしていなくても、Cline が何かを説明する際に「図示した方がわかりやすそうだ」と判断すると、突然この Skill が発動して図が飛んでくることがあることです。Skills の description に「システム設計、アーキテクチャ可視化、プロセスフロー説明」と書いてあるので、Cline が「今の説明は図にした方がいいな」と考えると自発的にスキルを使うようです。予期しないタイミングで図が届くのは、なかなか楽しい体験です。

まとめ

今回は、Cline の Skills で Mermaid ダイアグラムを生成する Skill を作ってみました。LLM がよく犯す Mermaid の構文エラーを事前に回避するガイドラインを盛り込んだことで、一発でレンダリングに成功する確率がだいぶ上がったと感じています。

Skills は、こうした「ちょっとした知識やコツ」を定義しておくのに向いています。SKILL.md はただのマークダウンファイルですから、作るのも修正するのも簡単ですし、チーム内で共有すれば全員が同じ品質の出力を得られます。そして、コンテキストウィンドウを汚さなくて済みます。

関連ブログ

• コーディング・エージェント Cline の Skills を試してみた
• AIエージェントと MCPサーバーで Oracle AWR レポートを生成・分析してみよう
• コード開発AIエージェント Cline ＋ LiteLLM + OCI Generative AI Grok 4 + Oracle Database MCP サーバーでAI駆動開発を始める

参考

• Cline 公式ドキュメント - Skills
• Cline 3.48.0: Skills and websearch make Cline smarter

付録 - SKILL.MD 全文

SKILL.md（クリックで展開）

---
name: mermaid-skill
description: 自然言語の説明からMermaidダイアグラムを生成するスキル。フローチャート、シーケンス図、ER図などの作成時に使用。システム設計、アーキテクチャ可視化、プロセスフロー説明、データモデル設計などのタスクで有効。
---

# mermaid-skill

このスキルは、ユーザーの自然言語による説明からMermaidスクリプトを生成し、@mermaid-js/mermaid-cli パッケージの `mmdc` コマンドを使用して図（PNG/SVG）としてレンダリングします。

## Usage

以下のようなタスクでこのスキルを使用してください：

- システムアーキテクチャの可視化
- プロセスフローの説明
- シーケンス図の作成
- ER図（データモデル）の設計
- 状態遷移図の作成
- その他Mermaidがサポートする図の生成

## Steps

1. 要件の理解: ユーザーの説明から、どのような図が必要かを把握する
2. 図タイプの選択: flowchart、sequenceDiagram、erDiagram、stateDiagram等から適切なタイプを選択
3. Mermaidスクリプトの生成: 以下のガイドラインに従ってスクリプトを直接生成（コード生成ではなく推論で生成）
4. ファイルへの保存: 生成したスクリプトを `.mmd` ファイルとして保存
5. レンダリング: `mmdc` コマンドを使用して図を生成
6. 結果の出力: 処理完了後、生成したファイル名を以下の形式で出力する

## Output Format

処理が完了したら、必ず以下の形式で生成したファイル名を出力してください：

生成完了:
- Mermaidスクリプト: <スクリプトファイルのパス.mmd>
- 画像ファイル: <画像ファイルのパス.png>

## Image Preview (Windows)

OSがWindowsの場合、処理の最後に `start` コマンドを使用して生成した画像ファイルを表示してください：

start <画像ファイルのパス.png>

## Rendering Command

Mermaidスクリプトをレンダリングするには、以下のコマンドを使用してください：

npx @mermaid-js/mermaid-cli -i <入力ファイル.mmd> -o <出力ファイル.png> --width 4096 --height 4096

- SVG形式で出力する場合は、出力ファイルの拡張子を `.svg` に変更

---

# Mermaid図生成ガイドライン

Mermaidスクリプトを生成する際には、以下の注意事項を必ず守ってください。

---

## 1. フローチャート（flowchart / graph）の注意事項

### 1.1 ノードラベルの改行

Markdown strings による改行（推奨・v10.1.0以降）

flowchart LR
    A["`複数行の
    テキスト`"]

従来の `<br>` による改行

flowchart LR
    A["複数行の<br>テキスト"]

※ `\n`（バックスラッシュ+n）はフローチャートでサポートされていません

### 1.2 ノードラベルの括弧

半角括弧 `()` はノード形状の定義に使用されるため、ラベル内で使う場合は二重引用符で囲む必要があります。

間違い: 括弧がノード形状として解釈される

flowchart LR
    A(メソッド名())

正しい: 二重引用符で囲む

flowchart LR
    A["メソッド名()"]

### 1.3 subgraphの注意事項

subgraph名にスペースや特殊文字が含まれる場合

flowchart TB
    subgraph sg1 ["My Subgraph Title"]
        A --> B
    end

subgraph間のエッジ
- `flowchart` を使用すればsubgraph間のエッジはサポートされています
- `graph` タイプでは正しく動作しない場合があります

### 1.4 予約語と特殊なケース

- `end` を小文字のままノードラベルに使用すると図が壊れます → `End` や `END` のように大文字を含める
- ノードIDの先頭が `o` や `x` の場合、エッジ記号と誤認されることがあります

---

## 2. ER図（erDiagram）の注意事項

- 属性の構成要素は、データ型 カラム名 制約（PK, "NOT NULL", UK, CK, FK のいずれか）の順で記述
- 制約がない場合は、制約欄には何も書かない
- NUMBER にスケールは指定できません。`NUMBER(精度,スケール)` はNG → `NUMBER(精度)` または `NUMBER` とする
- VECTOR にデータフォーマットは指定できません。`VECTOR(次元数, データフォーマット)` はNG → `VECTOR(次元数)` または `VECTOR` とする

---

## 3. シーケンス図（sequenceDiagram）の必須ルール

### 3.1 禁止文字一覧（最重要）

メッセージラベル、Note、participant エイリアスでは、以下の文字を絶対に使用しないでください：

| 禁止文字 | 理由 |
|---------|------|
| `<br>` `<br/>` | CLI環境（mmdc/mermaid-cli）でパースエラーを引き起こす |
| `\n` | Mermaidでサポートされていない |
| `{` `}` | 波括弧はMermaidの構文要素として解釈される |
| `'` | シングルクォートがトークン境界を壊す |
| `"` | ダブルクォートが文字列リテラルの終端と誤認される |
| `;` | セミコロンが文の終端として解釈される |
| バッククォート | バッククォートがMarkdown文字列の開始と誤認される |
| `(a, b)` | 括弧内のカンマが引数区切りとして解釈される場合がある |

### 3.2 改行が必要な場合の対処法

`<br>` や `\n` は使用せず、以下の方法を使用：
1. 複数のメッセージに分割する（推奨）
2. スペースやハイフンで区切る
3. 情報を簡潔にまとめる

### 3.3 note over の参加者数制限

- `note over` には最大2つの参加者までしか指定できません
- 3つ以上の参加者を指定するとパースエラーになります

### 3.4 特殊文字を含むラベルの引用符

- participantラベルにスペースを含む場合は、二重引用符で囲む
- ただし、引用符内であっても禁止文字は使用しない

### 3.5 コードスニペットをラベルおよびNoteに含めない（重要）

メッセージラベルおよびNoteにコードや関数呼び出しの詳細を記述しないでください。自然言語で簡潔に説明してください。

### 3.6 ラベルおよびNoteの長さと形式

- メッセージラベルおよびNoteは1行あたり50文字以内を目安に
- 動詞＋目的語のシンプルな形式を推奨

### 3.7 participant エイリアスの注意事項

- エイリアス名に以下の文字を含めない: `/` `(` `)` `&` `+`
- スペースを含む場合は二重引用符で囲む

### 3.8 rect（背景色）の構文

`rect` は `over` キーワードをサポートしていません。

### 3.9 グルーピングと視覚的な区分け（推奨パターン）

Note over + rect の併用を推奨。推奨カラーパレット：

| 用途 | 推奨色 | RGB値 |
|------|--------|-------|
| 準備フェーズ | 淡い緑 | `rgb(200, 230, 200)` |
| 実行フェーズ | 淡い青 | `rgb(200, 200, 230)` |
| エラー処理 | 淡い赤 | `rgb(230, 200, 200)` |
| オプション処理 | 淡い黄 | `rgb(230, 230, 200)` |
| 外部連携 | 淡い紫 | `rgb(220, 200, 230)` |

---

## 4. 生成前のセルフチェック

フローチャート:
- end が小文字のみで使われていないか
- 括弧を含むラベルが二重引用符で囲まれているか
- subgraph間のエッジを使う場合、flowchart を使用しているか

シーケンス図:
- メッセージラベルおよびNoteに禁止文字が含まれていないか
- メッセージラベルおよびNoteにコードスニペットが含まれていないか
- 各メッセージラベルおよびNoteが50文字以内か
- note over の参加者が2つ以下か
- 特殊文字を含むparticipantラベルは二重引用符で囲んでいるか
- rect に over キーワードを使用していないか
- rect の背景色は淡い色（RGB値200前後）を使用しているか

---

## 5. パースエラー発生時のリカバリ手順

1. エラーメッセージの確認: エラー箇所の行番号と期待されているトークンを確認
2. 禁止文字の特定: エラー箇所周辺のラベルやNoteに禁止文字が含まれていないか確認
3. コードスニペットの確認: ラベルやNoteにコードや関数呼び出しが含まれていないか確認
4. 構文の確認: `rect over` のような誤った構文が使用されていないか確認
5. ラベルおよびNoteの簡略化: 自然言語の短い説明に書き換える
6. 段階的な確認: 問題のある部分を特定するため、図を部分的に生成して動作を確認