graphify

Graphify

Graphify は CLI です。このスキルでのすべてのリクエストは、スラッシュコマンドや場当たり的な Python スクリプトではなく、実際の graphify … コマンドを主な手段として処理します。

「どの範囲を対象に、どの graphify コマンドを実行すればこの質問に答えられ、次に何を読むべきか？」 が主な質問である場合に、このスキルを使用します。

このスキルでは、次の作業を行います。

1. リクエストを1つのグラフパケットに分類する
2. CLI モードを1つ選ぶ
3. 実行時間やトークンコストが急増する前にコーパスの範囲を絞る
4. 成果物と、品質が低下した出力があれば、その事実を正確に報告する
5. 検索のみ、Wiki のみ、またはプロジェクトメモリに関する作業を、適切な隣接スキルに振り分ける

実際のフラグを含むすべてのコマンドについては、references/cli-command-map.md をお読みください。 インストールする前に、特に jeo / jeopi / gjc / opencode については、references/install-matrix.md をお読みください。 依頼の内容が不明な場合は references/mode-packets-and-route-outs.md を、ネイティブ抽出の品質が低い場合は references/build-and-fallback-recipes.md をお読みください。

CLI クイックスタート

pip install graphifyy                       # PyPI package is graphifyy; the binary is graphify
graphify --version

graphify scope                              # what would actually be graphed?
graphify update .                           # build -> .graphify/graph.json + .graphify/GRAPH_REPORT.md
graphify summary                            # hubs, communities, representative nodes
graphify query "where is auth enforced?" --budget 1500
graphify explain <node>                     # one node, plain language
graphify path <source> <target>             # shortest path between two nodes
graphify tree <node> --depth 2              # local neighbourhood
graphify export html                        # -> .graphify/graph.html

回答の正確性を保つための重要な事実が3つあります。

• graphify build は存在しません。 ビルドコマンドは graphify update です。graphify build --help はエラーを表示せずにルートのヘルプへフォールスルーします。
• 状態は graphify-out/ ではなく .graphify/ に保存されます。 graphify-out/ は旧レイアウトです。graphify migrate-state で移行できます。すべての --graph <path> フラグの既定値は <cwd>/.graphify/graph.json です。
• graph.html は graphify update では生成されません。 graphify export html で生成されます。

このスキルを使用する場合

• ユーザーが GRAPH_REPORT.md、graph.json、graph.html、コードベースのグラフ、または永続的なナレッジグラフを明示的に求めている
• リクエストがリポジトリ／コーパスの構造、関係の追跡、パスクエリ、または現在のセッション終了後も保持すべきアーキテクチャの調査に関するものである
• コーパスにコード、ドキュメント、PDF、メモ、スクリーンショットが混在しており、ユーザーが永続的な構造化レイヤーを1つ求めている
• ユーザーが生のファイルを読み直すのではなく、既存のグラフを更新、クエリ、または説明したい
• ユーザーが差分や PR について、変更を考慮したレビュー用の情報、影響を受ける実行フロー、またはリスクスコアを求めている
• ユーザーが Graphify を jeo、jeopi、gjc、opencode、Claude、Codex、Gemini、またはその他の対応エージェントにインストールしたい

このスキルを使用しない場合

• シンボル、ファイルの所有者、設定ファイルの場所、または参照チェーンを見つけるだけの場合 → codebase-search
• 永続的な Markdown ナレッジベースや、整理して保存する調査メモを求めている場合 → llm-wiki
• プロジェクト／リポジトリのメモリ、マニフェスト、またはエージェント間の引き継ぎパケットを求めている場合 → opencontext
• 永続的なグラフではなく、依存関係に限定した JS/TS 分析や、手早いリポジトリツリー図が必要な場合
• 具体的な Graphify の依頼を伴わない、一般的な GraphRAG／テキスト KG アーキテクチャの議論

jeo / jeopi / gjc / opencode へのインストール

graphify install [platform] が受け付ける ID は、次のものに限られます：claude、codex、gemini、 opencode、aider、copilot、claw、droid、trae、trae-cn、hermes、kimi、kiro、 antigravity、antigravity-windows、vscode-copilot-chat、windows、vscode。

jeo、jeopi、gjc はプラットフォーム ID ではありません — graphify install jeo は、 graphify install agents と同じように失敗します（error: unknown platform）。このリポジトリの setup-all-skills-prompt.md によると、これら 3 つは共有の ~/.agents/skills ルートをネイティブに検出します。 このルートには、無条件の universal ID がファイルを配置します。したがって：

# CLI for everyone
pip install graphifyy && graphify --version

# skill into the shared root that jeo, jeopi, gjc and sst/opencode all read
npx skills add https://github.com/akillness/jeo-skills --skill graphify -a universal
ls "${SKILLS_ROOT:-$HOME/.agents/skills}/graphify/SKILL.md"

# optional: opencode plugin + tool.execute.before hook (sst/opencode only)
graphify install opencode            # or: graphify install opencode --project

graphify install opencode --project は .opencode/skills/graphify/SKILL.md、 .opencode/plugins/graphify.js、.opencode/opencode.json、および AGENTS.md のセクションを書き込みます。 graphify install claude --project は .claude/skills/graphify/SKILL.md、 .claude/settings.json の PreToolUse フック、および CLAUDE.md のセクションを書き込みます。

アーカイブされた Go 製の opencode-ai/opencode TUI にはスキルローダーがありません — graphify install opencode を実行しても、そこでスキルは表示されません。コマンドファイルとして橋渡しするか、CLI を使用してください。詳細： references/install-matrix.md。

手順

ステップ 1：リクエストを 1 つのパケットに正規化する

• repo-structure-packet — 編集前にコードベースまたはサブシステムをマッピングする
• relationship-trace-packet — 既存のグラフからパス／クエリ／説明に関する質問に答える
• mixed-corpus-memory-packet — コード＋ドキュメント＋アセットを横断する永続的な構造を構築する
• review-diff-packet — 変更されたファイルのレビューコンテキストまたは影響を受けるフローを作成する
• install-packet — 常時利用できるように Graphify をエージェントに導入する
• refresh-or-fallback-packet — 既存のグラフを更新する、出力が不十分な場合に復旧する、またはフォールバックする

ユーザーがすでに持っているパケットから始めてください。あらゆるリクエストを機能紹介に無理に通さないでください。

ステップ 2：CLI モードを 1 つ選ぶ

モード	主なコマンド
cli-build	graphify scope → graphify update .
cli-query	graphify summary → query / explain / path / tree
cli-export	graphify export html|wiki|obsidian|svg|graphml|neo4j
incremental-refresh	graphify check-update → graphify update / watch / hook install
review-context	graphify review-context / affected-flows / detect-changes
agent-serve	graphify serve（graph.json 用の stdio MCP サーバー）
install	graphify install <platform> または ~/.agents/skills 経由の方法
structural-fallback	ネイティブ抽出結果が空または誤解を招く場合に、事実に即した最小の構造グラフを構築する

主なモードを 1 つ指定してください。フォールバックについては最大 1 つまで言及してください。

ステップ 3：実行に時間をかける前にスコープを絞る

不慣れな対象では、まず graphify scope を実行してください。適切なデフォルトは次のとおりです。

• リポジトリ全体のアーキテクチャが本当に求められている場合に限り、リポジトリのルート
• 実装作業では src/、app/、packages/<pkg>/、または 1 つのサービスディレクトリ
• コーパスのグラフ化では raw/、docs/、またはコードと資料が混在する調査フォルダー
• 再構築ではなくクエリ／更新が目的の場合は、既存の .graphify/

実行時の動作に期待するのではなく、--scope auto|committed|tracked|all と .graphifyignore を使用してください。 リクエストが実際には検索／参照であれば、codebase-search に振り分けてください。

ステップ 4：必要最小限のコマンドを実行する

モードに必要なコマンドだけにしてください。ユーザーが 1 つの質問をしているのに、ビルド、エクスポート、Wiki、監視ループを連続して実行しないでください。

ステップ 5：品質が低下した出力は正直に伝える

確認済みの動作：LLM API キーが設定されていなくても、graphify update . は graph.json と GRAPH_REPORT.md を書き込みますが、次のメッセージが表示されます。

[graphify label] warning: community labeling failed (...); using Community N placeholders.
[graphify describe] description generation failed (...); continuing without descriptions.

この場合、グラフの構造は完成していますが、ラベルや説明は付いていないと伝え、バックエンドの設定後に graphify update --fill-missing を実行することを提案してください。プレースホルダーである Community N という名前を、意味のあるクラスター名として決して提示しないでください。

Step 6: 成果物を順番に読む

1. .graphify/GRAPH_REPORT.md
2. graphify summary（エージェントでの作業では、HTML より低コストで要点を絞って確認できます）
3. .graphify/graph.html（graphify export html の実行後、人間が確認するため）
4. 最後に .graphify/graph.json を確認します。貼り付けるより、graphify query --budget <n> を優先してください。

Step 7: 隣接する作業は適切なツールに振り分ける

• codebase-search — グラフ化する前に、完全一致するテキスト、シンボル、設定の所有者、影響範囲をマッピングします
• llm-wiki — ナラティブの統合、Wiki ページ、長期運用する Markdown ナレッジベース
• opencontext — 検索可能な意思決定記録、マニフェスト、安定したリンク、プロジェクトメモリーの引き継ぎ
• survey — Graphify を採用する前のツールやプラットフォームの比較

Jevgrep のソース検出を明示的に依頼された場合は、.mex/context やスコープを絞ったソースツリーではなく jevgrep に従ってください。リモートコンテンツとコストに関するゲートは別途適用されます。グラフの関係性には、ここで query ／ path ／ explain を使用してください。Jevgrep は、デフォルトではグラフ成果物をアップロードせず、グラフの再構築も担当しません。

ユーザーが「グラフを構築またはクエリして」と依頼した場合は、ここで作業します。「ファイルをすぐに見つけて」「これを Wiki ノートとして記録して」「これをプロジェクトメモリーとして保存して」と依頼された場合は、適切なツールに振り分けます。

Step 8: 簡潔なグラフ概要を返す

パケット · 主なモード · 実際に実行したコマンド · 対象範囲 · 作成した成果物 · 出力の品質が低下していたか、フォールバックだったか · 次に実行するコマンドを 1～3 個 · 次のステップが別のツールの担当である場合は、その振り分け先を 1 つ。

出力形式

必ず、グラフ構築概要、グラフクエリ概要、グラフ更新概要、レビューコンテキスト概要、または Graphify インストール概要を、次の内容とともに返してください。

• 手元にあるパケットと、主なモードを 1 つ
• 実際に実行したコマンドと、その対象範囲
• .graphify/ 以下に存在するファイル、または作成したファイル
• 品質が低下した出力、プレースホルダー、フォールバック出力の明示
• 生の graph.json より先に GRAPH_REPORT.md ／ graphify summary を読んだこと
• 隣接する作業が次のステップを担う場合の振り分け先を 1 つ

例

例 1: 編集前にリポジトリを理解する

入力

コードに手を加える前に、アーキテクチャを理解できるよう、このリポジトリをマッピングしてください。

望ましい出力の方向性

• repo-structure-packet、モード cli-build
• graphify scope → graphify update . → graphify summary
• .graphify/GRAPH_REPORT.md と .graphify/graph.json を報告し、graph.html の生成には graphify export html が必要であることも伝えます

例 2: 既存のグラフから関係性をたどる

入力

すでにグラフがあります。認証コントローラーと請求処理の間には何がつながっていますか？

望ましい出力の方向性

• relationship-trace-packet、モード cli-query
• graphify summary → graphify path <auth> <billing> → graphify explain <node>
• 再構築は不要

例 3: 差分をレビューする

入力

この PR では実際に何が変更されていますか？差分をそのまま出すのではなく、レビュアー向けのコンテキストが欲しいです。

望ましい出力の方向性

• review-diff-packet、モード review-context
• graphify review-context --base main --detail-level standard と graphify affected-flows --base main --json

例 4: エージェント向けにインストールする

入力

jeo、jeopi、gjc、opencode 用に graphify をインストールしてください。

望ましい出力の方向性

• install-packet
• pip install graphifyy を実行し、jeo／jeopi／gjc には -a universal を使って ~/.agents/skills にスキルをインストールします。必要に応じて graphify install opencode も実行します。
• graphify install jeo は有効なプラットフォーム ID ではないことを明確に伝えます

例 5: 実際には検索の依頼

入力

この設定がどこで定義され、どこから参照されているのかだけを知りたいです。

望ましい出力の方向性

• codebase-search に振り分け、グラフは構築しません

ベストプラクティス

1. 実在する graphify コマンドを最初に示し、決して作り出さないでください。graphify build は存在しません。
2. graphify-out/ ではなく .graphify/ を使用してください。レガシーリポジトリでは graphify migrate-state を使用してください。
3. 見慣れないコーパスで負荷の高いビルドを実行する前に、graphify scope を実行してください。
4. 生の graph.json よりも GRAPH_REPORT.md と graphify summary を優先し、graphify query --budget <n> でトラバーサルの上限を設定してください。
5. build、query、export、refresh、review、serve、install、fallback はそれぞれ独立したモードとして扱ってください。
6. プレースホルダーの Community N ラベルや説明の欠落は、成功ではなく品質低下として報告してください。
7. アドホックな再ビルドではなく、継続的に最新状態を保つために graphify hook install または graphify watch を使用してください。
8. .graphify アーティファクトをコミットする前に、graphify portable-check を実行してください。
9. 構造的フォールバックは、隠れた失敗ではなく、正直に示す第一級のモードとして扱ってください。
10. 検索を優先する作業は codebase-search に、物語的なメモリーは llm-wiki に、プロジェクトのメモリーは opencontext に振り分けてください。
11. graphify の wiki ビルド後、または pip install --upgrade graphifyy の実行後は、[[…]] リンクが壊れているように見える場合、scripts/patch_wikilink.py を実行してください。graphify のジェネレーターは、slug 化された Community_36.md ページに解決されない raw-label の [[Community 36]] リンクを出力します。このパッチャーはすべてのリンク先を [[slug|label]] に正規化し、冪等に動作します。アップグレード後も修正が維持されるよう、インストール／アップグレード手順（jeo では graphify update . の前に実行する post-implementation フック）に組み込んでください。

参考資料

• CLI コマンド一覧 — 作業別にまとめたすべてのコマンドとフラグ
• インストールマトリックス — プラットフォーム ID、jeo／jeopi／gjc／opencode の経路
• モード別パケットと振り分け先
• ビルドとフォールバックのレシピ
• scripts/patch_wikilink.py — 冪等なウィキリンク正規化パッチ（--self-test、--check）
• ../codebase-search/SKILL.md · ../llm-wiki/SKILL.md · ../opencontext/SKILL.md
• Graphify の上流リポジトリ：https://github.com/Graphify-Labs/graphify
• Graphify の PyPI：https://pypi.org/project/graphifyy/