この記事ではAIエージェント向けスキルの実例として、自然言語から検証付きの技術図を生成するArchifyの使い方を掘り下げます。エージェント基盤そのものの選び方は AIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 をご覧ください。
- ・導入は
npx skills add tt-a1i/archify -gの1行。Claude Code・Codex CLI・Cursor・OpenCodeに同時対応するAgent Skill。 - ・エージェントは型付きJSON（JSON IR）を書くだけ。図の描画と検証はArchify側のNode.js CLIが決定論的に行う。
- ・
showcase品質では9項目の幾何チェックを全通過しないと出力されない。「検証を通らない図は出さない」設計。 - ・Architecture Deltaで2つのスナップショットをBefore / Delta / Afterで差分表示できる（設計レビュー・PR用）。
- ・依存パッケージはゼロ。Node.js 18以上だけで動く。ライセンスはMIT。
1. Archifyとは：45,000★を超えたAgent Skillの現在地
Archifyは、システムの説明文や既存のMermaidから「アーキテクチャ図」「ワークフロー図」「シーケンス図」「データフロー図」「ライフサイクル図」の5種類を、機械検証を通した単一HTMLとして生成するAgent Skillだ。ライセンスはMIT、リポジトリはtt-a1i/archifyにある（archify github で検索して辿り着きたい場合もこのURLが正）。
まず数字を更新しておきたい。本記事の初出時点（2026年5月）でArchifyはGitHub 213スターの小さなプロジェクトだったが、2026年9月4日 09:55 JST にGitHub APIで実測した時点で45,821スター・2,937フォークまで拡大している。増加が集中したのは2026年8月末で、リポジトリはこの時期にGitHub Trendingへ乗ったことがTrendshiftのバッジ掲載（README冒頭）からも確認できる。なお日次のスター増加数はGitHub APIの認証なしでは遡れないため、本記事では初出時213★（2026年5月）と実測45,821★（2026年9月4日 09:55 JST）という2点の実測値のみを根拠とし、途中の増加ペースは断定しない。
1.1 「Claude専用のzipスキル」ではなくなった
初出時のArchifyは、Claude.aiにzipをアップロードして使うClaude専用スキルだった。現在の公式READMEはArchifyを「Cursor・Claude Code・Codex CLI・OpenCode向けのNode.jsレンダリング／検証システム」と定義している。 リポジトリのtopicsにもcodex・opencode・deepseek-harness・mermaid-alternativeが並ぶ。「Claude Skill」という枠でこのツールを理解していると、対応範囲を実際より狭く見積もることになる。
1.2 設計思想が変わった：エージェントは描かない、JSONを書く
より本質的な変化は内部設計だ。初期版は「Claudeが直接SVGを組み立てる」構成で、図の品質はモデルの推論に依存していた。現在はエージェントが型付きJSON（JSON IR）を書き、Archify側のNode.js CLIがそれを決定論的にHTML/SVGへコンパイルする二層構成になっている。
説明文 または 既存Mermaid"] --> A["エージェント
Claude Code / Codex CLI / Cursor / OpenCode"] A --> J["型付きJSON IR
schemas/*.schema.json に適合"] J --> V["archify validate
9項目の幾何チェック"] V -->|"errors 0 / warnings 0"| R["archify render
決定論的コンパイル"] V -->|"不合格"| D["診断コード付きで差し戻し
rule code / subject / repair"] D --> A R --> O["単一HTML
PNG / SVG / WebM / 1200x630 共有カード"]
この分離が効いてくるのは「同じJSONからは同じ図が出る」点だ。モデルの機嫌で配置が変わらないため、生成物をリポジトリに置いて差分を取ることに意味が出る。後述するArchitecture Deltaはこの性質の上に成り立っている。
2. Archifyの使い方：インストールから最初の図まで
導入手順は初出時から完全に置き換わっている。現在の推奨は次の1行だ。
npx skills add tt-a1i/archify -g
skillsはVercel Labsが公開しているnpmパッケージ（”The open agent skills ecosystem”）で、本記事執筆時点の最新版は1.5.23。このnpx skillsという配布経路自体はArchify固有のものではなく、Googleが公式Agent Skillsリポジトリを公開した流れの中で標準化が進んでいる（Skillは標準仕様になる｜Googleが公式Agent Skillsリポジトリを公開、npx skillsで何が変わるか）。この1コマンドで、インストール済みの対応エージェントそれぞれの標準スキルディレクトリへArchifyが配置される。-gはグローバル導入で、リポジトリローカルに入れたい場合は-gを外す。
上記の
npx skills addそのものは、本記事の実行環境ではネットワーク経由のインストーラ実行が制限されており未実行です。かわりに、①npmレジストリでskillsパッケージの実在とバージョン（1.5.23）を確認、②リポジトリをgit cloneして配置されるスキル本体（archify/）の中身とCLIの動作を実測、という2点で裏取りしています。後述する数値・チェック項目はすべて②で実際に実行した結果です。
2.1 エージェント別の配置先
READMEの「Installation options」表に、どのエージェントがどこにスキルを置くかが明記されている。トラブル時はこのパスを直接見るのが早い。
| エージェント | 配置先 | 対応範囲 |
|---|---|---|
| Claude Code | ~/.claude/skills/ または .claude/skills/ |
レンダラ＋検証の全機能 |
| Codex CLI | ~/.agents/skills/ または .agents/skills/ |
レンダラ＋検証の全機能 |
| opencode | ~/.config/opencode/skills/、.opencode/skills/、.agents/skills/ |
レンダラ＋検証の全機能 |
| Cursor | skills CLIが生成するグローバル／プロジェクト別コマンドに従う |
レンダラ＋検証の全機能 |
| Claude.ai | Settings → Capabilities → Skills からarchify.zipをアップロード |
サンドボックスのNode.js実行可否に依存 |
| Project Knowledge | プロジェクトにarchify.zipをアップロード |
プロンプト駆動のフォールバック |
Archifyの検証とレンダリングは
node bin/archify.mjsという実プロセスが担います。Claude CodeやCodex CLIはローカルでNode.jsを起動できるため全機能が使えますが、Claude.aiのアップロード版はサンドボックス側のNode.js実行可否に左右されます。READMEもClaude.ai欄だけ「Depends on Node.js access in the sandbox」と条件付きで書いており、Project Knowledge経由に至っては「プロンプト駆動のフォールバック」と明記されています。検証機能を目当てに使うならCLI系エージェントを選ぶのが確実です。
2.2 最初の1枚：リポジトリは不要
READMEは「No repository is required」と明言している。チャットで構成を説明するだけでよい。
Reactフロントエンド、Node.js API、PostgreSQL、Redisキャッシュ、AWSでホスト。
この構成のアーキテクチャ図を archify で作って。
エージェントはこの説明から型付きJSONを起こし、validateを通してからHTMLを出力する。図を直すときもチャットで済む。「Redisを左へ」「認証サービスをマゼンタに」「Kafkaを追加」と伝えれば、エージェントがJSONの該当部分を書き換えて再検証する。SVGを直接編集するのではなくJSONを編集するので、修正のたびに検証がやり直される点が従来型のAI作図と違う。
2.3 既存のMermaidを持ち込む
スキル定義（archify/SKILL.md）のdescriptionには、入力として「plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input」を受け付けると書かれている。すでにMermaidで書いた図の資産があるなら、貼るだけで移行できる。 リポジトリのtopicsにmermaid-alternativeが入っているのはこの経路を想定しているためだ。
3. 対応エージェント：Claude Code・Codex CLI・Cursor・OpenCode
「ArchifyはClaude用か」という問いには、はっきり「違う」と答えられる。ここは初出時点から最も大きく変わった部分だ。
・Claude Code — 初期からの対応。~/.claude/skills/に置くだけで認識される
・Codex CLI — ~/.agents/skills/。CHANGELOGではv2.13.0でCursorと並べて第一級サポートとして明記された
・Cursor — v2.13.0で「First-class Cursor onboarding」として追加。公式はskillsCLIが出力する明示的なコマンドを使う方式を案内しており、skills use --agent cursorのようなランチャは提供していないと明記している
・opencode — ~/.config/opencode/skills/ほか3経路
・DeepSeek Harness — v2.15.0で追加された任意導入の統合。dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0。ただし公式は「DeepSeekの公式製品ではない」「開発者プレビュー版@deepseek-ai/dsh@0.1.0-rc.6向けのコミュニティ統合」と明示している
1つのスキルを多数のエージェントへ配る設計は、いまのAgent Skill全体の潮流でもある（Agent Skill Creator解説｜スキルを自動生成し17プラットフォームへ配るOSSの品質ゲートを実測）。
エージェントごとに別実装があるわけではありません。公式は「one portable
archify/SKILL.md」を保つ方針を明記しており、対応エージェントが増えても本体は同じです。増えているのは配置先のパスと導入コマンドのバリエーションであって、図の生成ロジックではありません。したがって「Codexで使うと機能が減る」といった心配は不要です（Claude.aiのサンドボックスだけが例外）。
4. JSON IRと自動検証：「検証可能な図」を実機で確かめる
Archifyを他のAI作図ツールと分けているのが検証層だ。初出記事ではJSON IRを「v3.0のロードマップ」として紹介していたが、これは既に実装済みで、現在の中核機構である。ここは実際に手元で動かして確かめた。
4.1 依存ゼロで動くことの確認
OS: macOS (Darwin 23.5.0, Apple Silicon) ／ Runtime: Node.js v22.13.1 ／ 対象:
tt-a1i/archify を git clone --depth 1 した v2.17.0-dev.1（安定版最新は v2.16.0）／ 検証日: 2026-09-04。本節以降の数値・チェック項目はすべてこの環境で実行した結果です。
git clone直後、npm installを一切実行せず（node_modulesが存在しない状態で）CLIを起動した。
node bin/archify.mjs doctor
結果は16項目すべて[ok]。Node.js v22.13.1 (requires >=18)、5種類すべてのレンダラ・スキーマ・サンプル、比較ランタイム、スタンドアロンのスキーマ検証器が揃っていることが確認できた。archify/package.jsonのdependenciesは実際に空で、ajvなどはすべてdevDependencies側にある。必要なのはNode.js 18以上だけという主張は実測どおりだった。
4.2 9項目の幾何チェックを全通過しないと出ない
showcase品質での検証を、同梱サンプル（checkout-platform.head.architecture.json）に対して実行した。
node bin/archify.mjs validate architecture examples/checkout-platform.head.architecture.json --quality showcase --json
返ってきたJSONには9つのチェックが並んでいた。内訳は次のとおり。
| チェック名 | 何を見ているか |
|---|---|
single_svg |
出力に<svg>ブロックがちょうど1つか |
finite_svg |
座標に有限でない値が混じっていないか |
orthogonal_arrows |
矢印が直交しているか |
label_route_clearance |
ラベルと経路が十分離れているか |
relationship_crossings |
関係線が不要に交差していないか |
relationship_corridors |
経路の通り道が曖昧になっていないか |
container_border_runs |
線がコンテナの枠に沿って走っていないか |
route_rhythm |
折れ・伸び・線分長のリズムが崩れていないか |
legend_clearance |
凡例が他要素と干渉していないか |
スキルの品質を外から測る試みは他にもあり、Microsoftは Agent Skills の評価フレームワークを公開している（Microsoft Waza｜Agent Skillsの品質を測るGo製評価フレームワークを解説）。Archifyが特徴的なのは、評価を外部ツールに委ねずスキル自身が出力ゲートとして内蔵している点だ。
同時に返るcompositionオブジェクトには実測値が入る。今回はstatus: "pass"、errors: 0、warnings: 0、properCrossings: 0、maxBends: 2、minLabelRouteClearance: 55、minSegmentPx: 20だった。「4項目しか報告されない受領書は基本検証であってshowcase合格ではない」とSKILL.mdが明示的に警告している点も、検証を演出でなく運用ゲートとして扱っている証拠だ。
4.3 出力HTMLの中身を数えた
renderを実行し、生成された単一HTMLを解析した。
| 実測項目 | 値 |
|---|---|
| 出力サイズ | 710,931バイト（約694KB、単一ファイル） |
| 内訳 | JavaScript 479,162B / CSS 186,015B / インラインSVG 18,875B |
<script>ブロック |
4個（すべてインライン） |
外部<img> / @import |
0件 / 0件 |
| 外部ホストへの参照 | fonts.googleapis.com・fonts.gstatic.com のみ |
prefers-color-schemeの出現 |
7箇所 |
| レンダリング所要時間 | 約0.3秒（ウォームアップ後・N=3の中央値） |
clone直後の初回実行だけは 4〜6秒かかりましたが、これはNode起動とモジュール初回ロードのコストで、レンダリング自体の速さではありません。ウォームアップ後に
standardとshowcaseを交互に3回ずつ回すと、中央値は 375ms と 291ms で試行ごとのばらつき（262〜413ms）に埋もれる差でした。出力バイト数も全6回で完全一致します。したがって品質プロファイルはレンダリング時間を実質変えないと読むのが正確です（単一入力・N=3の測定なので、この結論は本サンプルの範囲に限ります）。
初出時に「単一HTMLに内包されるJSは約3KB」と書いていましたが、v2.17.0-dev.1の実測では479KBでした。約160倍です。この間にビューア側へノード検索・経路プローブ・意味レンズ・ガイド付きストーリー・共有カード生成といった対話機能が入ったためで、いまのArchifyの出力は「静的な絵」ではなく単一ファイルで動く小さなアプリケーションと捉えるのが正確です。
4.4 Architecture Delta：2つの図を差分で比べる
v2.13.0で追加されたcompareは、設計レビューやPRレビューを想定した機能だ。同梱の2スナップショットで実行した。
node bin/archify.mjs compare architecture examples/checkout-platform.base.architecture.json examples/checkout-platform.head.architecture.json out.html --json
ウォームアップ後のN=3で中央値0.96秒。受領書には両スナップショットのrawSha256とsemanticSha256、そしてcomponents: added 1 / changed 1 / removed 1 / moved 1という機械的な差分が並んだ。completeness: "complete"、proofLevel: "authored"も返る。
+ / ~ / − / ↔と線種で示され、色や動きに依存せず読める。出典: tt-a1i/archify（MIT）CHANGELOGのArchitecture Delta項には「リスク・影響範囲・安全性・マージ可否・検証済みPR影響を主張しない（never claims risk, blast radius, safety, mergeability, or verified PR impact）」と書かれています。差分として提示するのは作者が書いた事実の変化だけで、その変更が危険かどうかは判断しない、という線引きです。AIツールの説明としては珍しく抑制的で、レビュー補助として信頼して使ううえではむしろ好ましい態度です。
4.5 リポジトリの実コードに紐づける（任意）
v2.13.0の「Revision-verified Repository Evidence Passport」を使うと、アーキテクチャ図の各コンポーネントを実際のソースへ結び付けられる。リポジトリURL・完全なコミットSHA・コンポーネントごとに1〜3個のリポジトリ相対パスを宣言し、--repo-rootを渡す。Archifyはローカルのorigin・コミット・blob・任意の行範囲を検証してからリンクを出力する。未検証・未固定（unpinned）の証跡は意図的に対象外で、プライベートリポジトリも範囲外だ。
5. 5種類の図の使い分け
図の種類選びは公式の表が最も端的だ。プロンプトに何を書けばよいかまで示されている。
| 種類 | 向いている対象 | プロンプトに含めるとよい情報 |
|---|---|---|
| Architecture | コンポーネント・サービス・ストレージ・境界 | スコープ、主要コンポーネント、主経路 |
| Workflow | CI/CD、承認フロー、ツール呼び出し、運用手順 | 参加者、順序、分岐、例外 |
| Sequence | API呼び出し、キャッシュフォールバック、認証、非同期トレース | 呼び出し元、呼び出し先、戻り、タイミング |
| Data Flow | パイプライン、データリネージ、個人情報、利用先 | ソース、変換、保存先、境界 |
| Lifecycle | 状態、リトライ、待機、終了状態 | 状態、イベント、リトライ・キャンセル経路 |
迷ったときは、CLIに直接聞ける。
node bin/archify.mjs guide "Show an API request with Redis cache miss"
5.1 対話機能：図を「読む」ための仕掛け
出力HTMLに入っている479KBのJSは、次のような読解支援を担っている。いずれもv2.12.0〜v2.16.0で段階的に追加された機能だ。
・Node Finder — ノード名で検索して絞り込む
・Authored Reachability — あるノードの上流／下流を推移的にたどり、一致したノード数・リンク数・最大ホップ数を表示する。#focus=<id>&reach=upstream の形でURL共有もできる
・Semantic Passport — ノードをクリックすると役割・種別・（設定していれば）検証済みソースへのリンクが出る
・ガイド付きストーリー — 作者が定義した章を順に再生する。推論はせず、書かれた経路だけをなぞる
・Reach Share Card — 上流／下流の探索結果から1200×630のPNGを書き出す
Reachabilityの説明には「これは作者が書いた到達可能性であって、影響範囲・破壊・リポジトリへの影響・実行時の因果ではない（explicitly authored reachability—not blast radius, breakage, repository impact, or runtime causality）」と明記されています。図が語れるのはJSONに書かれた事実までで、そこから先は推測しない。Archifyの設計方針はここで一貫しています。
6. 他ツールとの比較：Mermaid・diagrams.net・Lucid
| 観点 | Archify | Mermaid | diagrams.net | Lucidchart | PlantUML |
|---|---|---|---|---|---|
| 入力 | 自然言語／既存Mermaid（エージェント経由でJSON IR） | 独自構文 | GUI操作 | GUI操作＋AI | 独自構文 |
| 出力の検証 | 9項目の幾何チェック（showcase） | なし | なし | なし | なし |
| 決定論性 | 同じJSONから同じ出力 | 高い | 手作業依存 | 手作業依存 | 高い |
| 差分比較 | Architecture Deltaで機械的な受領書つき | テキストdiff | ファイル比較 | 版履歴 | テキストdiff |
| 成果物 | 単一HTML（約694KB）＋PNG/SVG/WebM/共有カード | SVG（レンダラ必要） | 各種 | 各種 | 各種 |
| 依存 | Node.js 18以上のみ | JS実行環境 | アプリ／Web | SaaS | Java |
| ライセンス | MIT | MIT | Apache 2.0 | 商用 | GPL |
6.1 Mermaidと競合しない
mermaid-alternativeというtopicが付いているものの、実際には併用が自然だ。MermaidはREADMEやIssueに数行で図を埋め込む用途で圧倒的に手軽で、テキストとして残る可搬性も高い。一方でMermaidは「書いたとおりに描く」ので、線が交差しても凡例が重なっても止まらない。
Archifyが向くのは、その図が何度もレビューされ、更新され、他人に説明される場合だ。設計レビュー資料・オンボーディング資料・PRに添える構成変更の説明など、図の品質と再現性が効く場面である。しかもArchifyはMermaidを入力として受け取れるので、「Mermaidで下書きして、清書と検証をArchifyに任せる」流れが成立する。
6.2 diagrams.net / Lucidとの違い
diagrams.netやLucidchartはGUIで自由に描ける汎用ツールで、表現力ではArchifyを上回る。ただし「テキストから起こす」「差分を機械的に取る」「CIに載せる」といった自動化はしにくい。Archifyの立ち位置は作図ツールというより、構成情報をコードとして扱うためのコンパイラに近い。
7. v2.4から2.16までの変化と、いま注意すべき制約
初出記事はv2.4（2026-04-18リリース）を対象にしていた。最新はv2.16.0（2026-08-30リリース）、開発版はv2.17.0-dev.1だ。主要な変化を挙げる。
| バージョン | 日付 | 主な追加 |
|---|---|---|
| v2.12.0 | 2026-07-23 | Last-Good Live Preview（preview）。実リポジトリを題材にした検証済み事例 |
| v2.13.0 | 2026-08-03 | Architecture Delta（compare）、リポジトリ証跡パスポート、Cursor第一級対応、構造化された修復受領書 |
| v2.14.0 | 2026-08-11 | visual-checkによるファーストスクリーン検証、ビューアUIの整理 |
| v2.15.0 | 2026-08-17 | 107個の出所付きブランドマーク、DeepSeek Harness配布 |
| v2.16.0 | 2026-08-30 | Workflow schema v2の制約駆動コンパイラ、ビューアUIの多言語化（en / zh-CN）、更新通知のみのバージョン確認 |
7.1 いま押さえておくべき制約
・Claude.aiアップロード版は全機能を保証しない。 検証・レンダリングはNode.jsプロセスに依存するため、サンドボックス次第で挙動が変わる
・ビューアUIの多言語化はen / zh-CNのみ。 v2.16.0でmeta.localeが入ったが日本語は対象外で、指定しなければ英語UIになる。図の中身（作者が書いたラベル）は日本語でも問題ない
・出力HTMLは約694KBある。 静的サイトに多数を埋め込む場合は転送量を意識したほうがよい
・リポジトリ証跡は公開GitHubのみ。 プライベートリポジトリ、コミット未固定の参照は意図的に対象外
・Architecture Deltaは危険度を判定しない。 差分の事実を出すだけで、マージ可否の判断材料にはならない
・開発版と安定版が並走している。 READMEはv2.17.0-dev.1を掲げているが、GitHub Releasesの最新安定版はv2.16.0。導入時にどちらが入るかは確認したほうがよい
7.2 来歴とライセンス
ArchifyはCocoon AI社のarchitecture-diagram-generator v1.0（MIT）を出発点としたfork rewriteで、SKILL.mdのメタデータにもbased_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)と明記されている。現在のライセンスはMIT。リポジトリにはTHIRD_PARTY_NOTICES.mdも同梱されている。
なお2026年8月時点でスポンサー企業が付いており、READMEにはAPINEBULA（アフィリエイトリンクと割引コード付き）とEverMindの記載がある。OSS自体はMITのままだが、READMEを読むときは商用リンクが混在している点を認識しておきたい。
まとめ
- ・
ArchifyはClaude専用スキルではなく、Claude Code・Codex CLI・Cursor・OpenCodeに対応するAgent Skill。導入はnpx skills add tt-a1i/archify -gの1行。 - ・エージェントは型付きJSON IRを書くだけで、描画と検証は依存ゼロのNode.js CLIが決定論的に行う。
- ・
showcaseでは9項目の幾何チェックを全通過しないと出力されない。実測でerrors 0 / warnings 0を確認した。 - ・出力は単一HTML約694KB（JS 479KB / CSS 186KB / SVG 19KB）。外部参照はGoogle Fontsの2ホストのみ。
- ・
compareで2スナップショットの意味的ハッシュと追加/削除/変更/移動を機械的に受け取れる。ただしリスク判定はしない。 - ・2026-09-04時点で45,821★。初出時の213★から大きく育ち、設計思想も入れ替わっている。
Mermaidを置き換えるツールというより、構成情報をコードとして扱い、検証を通してから配るための基盤だと捉えると使いどころが見えてくる。README一枚に貼る図ならMermaidで十分だが、何度もレビューされる図ならArchifyの検証層が効く。
参照ソース
- tt-a1i/archify — GitHubリポジトリ（README / CHANGELOG / SKILL.md、MIT、2026-09-04時点で45,821★）
- Archify プロジェクトページ（公式サイト・シナリオガイド・Proof Lab）
- skills — npmパッケージ（vercel-labs、v1.5.23、
npx skills addの提供元） - Cocoon-AI/architecture-diagram-generator（Archifyのfork元、MIT v1.0）
