bybit-exchange/svg-diagram

svg‑diagram – AIエージェントが生成するSVGのためのハウススタイルとリンター

何であるか – 手書きのSVG図の厳格な視覚スタイルを定義し、そのスタイルに従って完成したSVGを検証するコマンドラインリンター（svg‑lint）を提供する、ゼロ依存の小さなNodeツール。リポジトリには、多くの人気のあるコーディングエージェント（Claude、Gemini、Copilotなど）にインストール可能な スキル（markdownファイル SKILL.md）が同梱されており、エージェントがボックスのサイズ、テキストの配置、接続線の描画、色の選択を正確に実行できるようにします。

AIエージェントにとってなぜ重要か – 現代のコード生成エージェントは、アーキテクチャスケッチ、フローチャート、ベンチマークなど、図を出力する必要があることがよくあります。曖昧な「見栄えよくして」ではなく、明確な算術的レシピを提供することで、出力は決定論的になり、プレーンテキストとしてレビュー可能になり、リンターで自動検証が可能になります。これにより、生成後の手動編集を減らし、エージェント間での一貫性を確保します。

主な特徴

• ハウススタイル – 固定されたviewBoxマージン、フォントサイズ、色の三つ組、矢印の幾何学、CJK対応フォントスタック、明示的なエスケープルール。すべてのルールは SKILL.md にドキュメント化されています。
• ゼロ依存のリンター – tools/svg‑lint/bin/svg‑lint.mjs という単一のNodeスクリプトで、npm install なしにどのマシンでも実行可能。12のチェック（エスケープ、viewBox、フォントスタック、ボックス寸法、ベースライン、間隔、矢印マーカー、オーバーフロー、重複、パレット、接続線の幾何学、ドキュメントモデルの健全性チェック）を実行します。
• エージェント非依存のインストール – npx skills add bybit-exchange/svg-diagram -g で、スキルとリンターが数十のエージェントに対応する適切なディレクトリにコピーされます。スキルのフロントマター name がインストールパスを決定するため、リポジトリの移動でもインストールが壊れません。
• 人間が読みやすい修正案 – 各リンター失敗は、現在の値、許容範囲/値、1行の「修復」提案を報告します。例：font-family: absent → 'PingFang SC', …。
• 準拠図のギャラリー – 10の例SVGが、すべてのルール（レイアウト、作成ループ、リンターゲート、データフロー、スキルライフサイクル、リポジトリアーキテクチャ、マルチエージェントインストール、CJKフォント処理、階層ルーティング、A/Bベンチマーク）を示しています。
• テストスイート – npm run lint:svg:all で同梱のSVGを検証；npm test で984のユニットテストを実行し、リンターとスキルの信頼性を保証します。

使い方

1. エージェント用にスキルをインストール：

   npx skills add bybit-exchange/svg-diagram -g   # すべてのエージェント向けグローバルインストール
   

2. 新しいエージェントセッションで図を要求。エージェントは svg‑diagram スキルを使用していると発表し、そこに定義された算術に従って図を生成します。
3. エージェントが diagram.svg を出力後、リンターで準拠を検証します：

   node ~/.claude/skills/svg-diagram/tools/svg-lint/bin/svg-lint.mjs diagram.svg
   

   マシン読み取り可能な出力には --json を追加します。
4. チェックが失敗した場合、修復ヒントに従ってSVGを編集するか、スキルの説明を調整して再実行します。

このプロジェクトが存在する理由 – AI生成図を「コードとしてレビュー可能」にするため：すべての座標が明示的で、すべてのスタイルがプレゼンテーション属性であり、リンターがレイアウトエンジンや外部CSSに頼らず、共有された視覚言語に準拠していることを保証します。これにより再現性が向上し、diffベースのレビューが簡素化され、CJK文字がプラットフォーム間で正しくレンダリングされることを保証します。

ライセンス – MIT。