How to use the graphify agent skill: build and query a knowledge graph

What the graphify skill makes the agent do

An agent skill is a SKILL.md instruction file, plus any supporting scripts, that an AI agent loads when a task matches its description. The graphify skill covers questions about a codebase, its architecture, file relationships and project content. When it runs, it turns a folder into a graph with community detection (clusters of related concepts) and surfaces central 'god nodes'.

The output has three parts: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md. Each edge is labelled EXTRACTED, INFERRED or AMBIGUOUS, so you can see which connections came straight from the source and which were guessed.

• Scan a folder of code, docs, papers, images, video or GitHub repos
• Save the graph in graphify-out/ so it persists across sessions
• Answer queries, shortest paths between concepts, and explanations of a single node

Install the graphify skill

Option 1: download the ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into .claude/skills/ inside a project if you want the skill only for that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.

The skill also needs the graphify Python package. The skill checks for it on first run and installs it if missing, using uv, pipx or pip, so you do not have to set it up by hand.

• Project scope: .claude/skills/ inside your project folder
• User scope: ~/.claude/skills/
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You can invoke the skill directly with /graphify followed by a path, or simply ask a question about the codebase. If graphify-out/graph.json already exists in the current directory, the agent is meant to answer codebase questions with a graph query first rather than re-scanning the files.

Explicit commands cover the rest of the workflow, such as rebuilding with --update, rerunning clustering with --cluster-only, or adding a URL with add.

• Build a graph: /graphify on the current directory, or /graphify <path>
• Incremental rebuild: /graphify <path> --update
• Ask a question: "How does the authentication flow connect to the database layer?"
• Find a link: /graphify path "AuthModule" "Database"
• Explain a node: /graphify explain "SwinTransformer"

Choose the right options for your output

The default run generates the HTML visualisation. Add flags for other formats. SVG is useful for embedding in Notion or GitHub, and GraphML opens in Gephi or yEd. Neo4j and FalkorDB exports write a cypher.txt file or push directly to a running database.

Use --mode deep for a more thorough extraction with richer INFERRED edges, and --whisper-model to choose a larger Whisper model for video or audio transcription.

• --svg exports graph.svg
• --graphml exports graph.graphml for Gephi or yEd
• --neo4j writes graphify-out/cypher.txt for Neo4j
• --mcp starts an MCP stdio server for agent access
• --wiki builds an agent-crawlable wiki with index.md and one article per community
• --no-viz skips visualisation and outputs only the report and JSON

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its setup step installs the graphify package and writes files into graphify-out/. If you pass GitHub URLs, it clones the repository. The 'add' command fetches a URL and saves it to ./raw. Video and audio transcription uses a Whisper model.

For sensitive or confidential code, be careful. Pushing to Neo4j or FalkorDB, or fetching URLs, can send data off your machine, and the agent may send content to a model provider. Review the skill's scripts and use a local path rather than a remote URL when the material is private.

• Runs scripts: yes, including package installation on first run
• Uses network: yes, for GitHub clones, URL fetches and database pushes
• Avoid database push or URL fetch for confidential repositories unless you have checked where data goes

Tips for useful graphs

Start with a focused folder rather than a whole monorepo, and check the report to confirm the grouping makes sense. Treat INFERRED and AMBIGUOUS edges as leads to verify in the source, not as facts.

If you edit code during a session, run graphify update . so the graph stays current. Use query, path and explain for focused questions; the report is better for broad architecture review.

• Verify INFERRED and AMBIGUOUS edges before relying on them
• Use --update for incremental rebuilds instead of full runs
• Read GRAPH_REPORT.md for a broad overview before asking detailed questions