Drive Graphify from its CLI to build, refresh, query, export, and serve a durable code/corpus knowledge graph. Use when the user wants `.graphify/GRAPH_REPORT.md`, `graph.json`, `graph.html`, `graphify update`/`summary`/`query`/`path`/`explain`/`tree`, change-aware review context, git-hook or watch-based refresh, a stdio MCP graph server, or an install into jeo, jeopi, gjc, opencode, Claude, Codex, or Gemini. Also covers the honest structural fallback when native extraction is empty or misleading. Route simple locate/reference work to `codebase-search`, narrative knowledge-base work to `llm-wiki`, and project-memory handoff to `opencontext`. Triggers on: graphify, graphify update, graphify query, knowledge graph CLI, GRAPH_REPORT.md, graph.json, codebase graph, graph refresh, graphify install, graphify serve, review context, affected flows.
Drive Graphify from its CLI to build, refresh, query, export, and serve a durable code/corpus knowledge graph. Use when the user wants `.graphify/GRAPH_REPORT.md`, `graph.json`, `graph.html`, `graphify update`/`summary`/`query`/`path`/`explain`/`tree`, change-aware review context, git-hook or watch-based refresh, a stdio MCP graph server, or an install into jeo, jeopi, gjc, opencode, Claude, Codex, or Gemini. Also covers the honest structural fallback when native extraction is empty or misleading. Route simple locate/reference work to `codebase-search`, narrative knowledge-base work to `llm-wiki`, and project-memory handoff to `opencontext`. Triggers on: graphify, graphify update, graphify query, knowledge graph CLI, GRAPH_REPORT.md, graph.json, codebase graph, graph refresh, graphify install, graphify serve, review context, affected flows.
allowed-tools
Bash Read Write Grep Glob
compatibility
Requires the `graphifyy` PyPI package (Python 3.10+) so the `graphify` CLI is on PATH. Assistant integrations exist for claude, codex, gemini, opencode, aider, copilot, claw, droid, trae, trae-cn, hermes, kimi, kiro, antigravity, vscode and windows variants; jeo, jeopi and gjc have no platform id and install through the shared `~/.agents/skills` root.
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:
classify the request into one graph packet,
choose one CLI mode,
scope the corpus before runtime or token cost explodes,
report artifacts and any degraded output truthfully,
route search-only, wiki-only, or project-memory work to the right neighboring skill.
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
graphify install <platform> or the ~/.agents/skills route
structural-fallback
build the smallest truthful structural graph when native extraction is empty or misleading
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
.graphify/GRAPH_REPORT.md
graphify summary (cheaper and more focused than the HTML for agent work)
.graphify/graph.html (after graphify export html) for humans
.graphify/graph.json last, and prefer graphify query --budget <n> over pasting it
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.
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
Lead with a real graphify command; never invent one — graphify build does not exist.
Write .graphify/, not graphify-out/; use graphify migrate-state for legacy repos.
Run graphify scope before an expensive build on an unfamiliar corpus.
Prefer GRAPH_REPORT.md and graphify summary over raw graph.json; cap traversals with
graphify query --budget <n>.
Keep build, query, export, refresh, review, serve, install, and fallback as distinct modes.
Report placeholder Community N labels and missing descriptions as degraded output, not success.
Use graphify hook install or graphify watch for ongoing freshness instead of ad-hoc rebuilds.
Run graphify portable-check before committing .graphify artifacts.
Treat structural fallback as a first-class honest mode, not a hidden failure.
Route search-first work to codebase-search, narrative memory to llm-wiki, project memory
to opencontext.
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.
