Graphify

Graphify

Graphify is a CLI. The primary path for every request in this skill is a real graphify … command, not a slash command and not an improvised Python script.

Use this skill when the main question is "which graphify command answers this, over what scope, and what should we read next?"

The job is to:

1. classify the request into one graph packet,
2. choose one CLI mode,
3. scope the corpus before runtime or token cost explodes,
4. report artifacts and any degraded output truthfully,
5. route search-only, wiki-only, or project-memory work to the right neighboring skill.

Read references/cli-command-map.md for the full command surface with real flags. Read references/install-matrix.md before installing anything — especially for jeo / jeopi / gjc / opencode. Read references/mode-packets-and-route-outs.md for an unfamiliar request, and references/build-and-fallback-recipes.md when native extraction is weak.

CLI quickstart

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

Three facts that keep answers truthful:

• graphify build does not exist. The build command is graphify update. graphify build --help silently falls through to the root help.
• State lives in .graphify/, not graphify-out/. graphify-out/ is the legacy layout; graphify migrate-state moves it. Every --graph <path> flag defaults to <cwd>/.graphify/graph.json.
• graph.html is not produced by graphify update. It comes from graphify export html.

When to use this skill

• The user explicitly wants GRAPH_REPORT.md, graph.json, graph.html, a codebase graph, or a persistent knowledge graph
• The request is about repo/corpus structure, relationship tracing, path queries, or architecture discovery that should survive the current session
• The corpus mixes code, docs, PDFs, notes, or screenshots and the user wants one durable structure layer
• The user wants to refresh, query, or explain an existing graph instead of re-reading raw files
• The user wants change-aware review context, affected execution flows, or risk scoring for a diff or PR
• The user wants Graphify installed into jeo, jeopi, gjc, opencode, Claude, Codex, Gemini, or another supported agent

When not to use this skill

• Only needs to find a symbol, file owner, config location, or reference chain → codebase-search
• Wants a persistent markdown knowledge base or filed research notes → llm-wiki
• Wants project/repo memory, manifests, or cross-agent handoff packets → opencontext
• Needs dependency-only JS/TS analysis or a quick repo tree diagram, not a durable graph
• Generic GraphRAG / text-KG architecture talk with no concrete Graphify ask

Install for jeo / jeopi / gjc / opencode

graphify install [platform] accepts exactly these ids: claude, codex, gemini, opencode, aider, copilot, claw, droid, trae, trae-cn, hermes, kimi, kiro, antigravity, antigravity-windows, vscode-copilot-chat, windows, vscode.

jeo, jeopi and gjc are not platform ids — graphify install jeo will fail the same way graphify install agents does (error: unknown platform). Per this repo's setup-all-skills-prompt.md, those three discover the shared ~/.agents/skills root natively, which the unconditional universal id populates. So:

# 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 writes .opencode/skills/graphify/SKILL.md, .opencode/plugins/graphify.js, .opencode/opencode.json, and an AGENTS.md section. graphify install claude --project writes .claude/skills/graphify/SKILL.md, .claude/settings.json PreToolUse hooks, and a CLAUDE.md section.

The archived Go opencode-ai/opencode TUI has no skill loader — graphify install opencode will not surface the skill there; bridge it as a command file or just use the CLI. Full detail: references/install-matrix.md.

Instructions

Step 1: Normalize the request into one packet

• repo-structure-packet — map a codebase or subsystem before editing
• relationship-trace-packet — answer a path/query/explain question from an existing graph
• mixed-corpus-memory-packet — build durable structure across code + docs + assets
• review-diff-packet — produce review context or affected flows for changed files
• install-packet — get Graphify into an agent for always-on use
• refresh-or-fallback-packet — update an existing graph, recover from weak output, or fall back

Start from the packet the user already has. Do not force every request through a feature tour.

Step 2: Pick one CLI mode

Name one primary mode. Mention at most one fallback.

Step 3: Scope before spending

Run graphify scope first on anything unfamiliar. Good defaults:

• repo root only when repo-wide architecture is genuinely the ask
• src/, app/, packages/<pkg>/, or one service directory for implementation work
• raw/, docs/, or a mixed research folder for corpus graphing
• an existing .graphify/ when the job is query/refresh rather than rebuild

Use --scope auto|committed|tracked|all and .graphifyignore instead of hoping runtime behaves. If the request is really locate/reference, route to codebase-search.

Step 4: Run the narrowest command set

Keep it to the commands the mode needs. Do not chain a build, an export, a wiki, and a watch loop when the user asked one question.

Step 5: Report degraded output honestly

Verified behavior: with no LLM API key configured, graphify update . still writes graph.json and GRAPH_REPORT.md, but prints:

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

When that happens, say the graph is structurally complete but unlabeled/undescribed, and offer graphify update --fill-missing once a backend is configured. Never present placeholder Community N names as meaningful clusters.

Step 6: Read artifacts in order

1. .graphify/GRAPH_REPORT.md
2. graphify summary (cheaper and more focused than the HTML for agent work)
3. .graphify/graph.html (after graphify export html) for humans
4. .graphify/graph.json last, and prefer graphify query --budget <n> over pasting it

Step 7: Route adjacent work outward

• codebase-search — exact text, symbol, config ownership, impact mapping before graphing
• llm-wiki — narrative synthesis, wiki pages, long-lived markdown knowledge bases
• opencontext — searchable decisions, manifests, stable links, project-memory handoff
• survey — tool/platform comparison before committing to Graphify

If the user asks "build or query the graph," stay here. If they ask "find the file fast," "file this as a wiki note," or "store this as project memory," route out.

Step 8: Return one concise graph brief

Packet · primary mode · commands actually run · scope · artifacts written · whether output was degraded or fallback · 1–3 next commands · one route-out if the next step belongs elsewhere.

Output format

Always return a graph build brief, graph query brief, graph refresh brief, review context brief, or Graphify install brief with:

• the packet in hand and one primary mode
• the real commands run, with their scope
• which files under .graphify/ exist or were created
• honest labeling of degraded, placeholder, or fallback output
• GRAPH_REPORT.md / graphify summary read before raw graph.json
• one route-out when neighboring work now owns the next step

Examples

Example 1: understand a repo before editing

Input

Map this repo so I can understand the architecture before touching code.

Good output direction

• repo-structure-packet, mode cli-build
• graphify scope → graphify update . → graphify summary
• reports .graphify/GRAPH_REPORT.md and .graphify/graph.json, and that graph.html needs graphify export html

Example 2: trace a relationship from an existing graph

Input

We already have a graph. What connects the auth controller to billing?

Good output direction

• relationship-trace-packet, mode cli-query
• graphify summary → graphify path <auth> <billing> → graphify explain <node>
• no rebuild

Example 3: review a diff

Input

What does this PR actually touch? I want reviewer context, not a diff dump.

Good output direction

• review-diff-packet, mode review-context
• graphify review-context --base main --detail-level standard and graphify affected-flows --base main --json

Example 4: install for our agents

Input

Install graphify for jeo, jeopi, gjc and opencode.

Good output direction

• install-packet
• pip install graphifyy, then the skill into ~/.agents/skills via -a universal for jeo/jeopi/gjc, plus optional graphify install opencode
• states plainly that graphify install jeo is not a valid platform id

Example 5: request is really search

Input

I just need to find where this config is defined and who references it.

Good output direction

• routes to codebase-search; does not build a graph

Best practices

1. Lead with a real graphify command; never invent one — graphify build does not exist.
2. Write .graphify/, not graphify-out/; use graphify migrate-state for legacy repos.
3. Run graphify scope before an expensive build on an unfamiliar corpus.
4. Prefer GRAPH_REPORT.md and graphify summary over raw graph.json; cap traversals with graphify query --budget <n>.
5. Keep build, query, export, refresh, review, serve, install, and fallback as distinct modes.
6. Report placeholder Community N labels and missing descriptions as degraded output, not success.
7. Use graphify hook install or graphify watch for ongoing freshness instead of ad-hoc rebuilds.
8. Run graphify portable-check before committing .graphify artifacts.
9. Treat structural fallback as a first-class honest mode, not a hidden failure.
10. Route search-first work to codebase-search, narrative memory to llm-wiki, project memory to opencontext.
11. After a graphify wiki build — or any pip install --upgrade graphifyy — run scripts/patch_wikilink.py if [[…]] links look broken. graphify's generator emits raw-label [[Community 36]] links that never resolve to its slugged Community_36.md pages; the patcher normalizes every link site to [[slug|label]] and is idempotent. Wire it into the install/upgrade step (jeo: the post-implementation hook ahead of graphify update .) so the fix survives upgrades.

References

• CLI command map — every command and flag, grouped by job
• Install matrix — platform ids, jeo/jeopi/gjc/opencode routes
• Mode packets and route-outs
• Build and fallback recipes
• scripts/patch_wikilink.py — idempotent wikilink-normalization patch (--self-test, --check)
• ../codebase-search/SKILL.md · ../llm-wiki/SKILL.md · ../opencontext/SKILL.md
• Graphify upstream: https://github.com/Graphify-Labs/graphify
• Graphify PyPI: https://pypi.org/project/graphifyy/