From a13fa2a7c79cc868d9eb2c408fc41a7ceb6fcae9 Mon Sep 17 00:00:00 2001
From: Linus Beckhaus <linus.beckhaus@thinktecture.com>
Date: Wed, 25 Feb 2026 11:47:16 +0100
Subject: [PATCH] feat(plugin): transform Claude Code plugin into
 self-contained installable package

Bundle MCP server config (.mcp.json), fix hook to use spawnSync with npx
fallback and read stderr (KuzuDB stdout workaround), wire plugin.json with
hooks/mcpServers paths, add guide skill with tools/resources/schema reference,
add AMP-compatible mcp.json to all skill dirs, and slim CLAUDE.md generator
by moving reference content into the guide skill.
---
 .../.claude-plugin/plugin.json                |  7 +-
 gitnexus-claude-plugin/.mcp.json              |  8 ++
 gitnexus-claude-plugin/hooks/gitnexus-hook.js | 38 +++++++--
 gitnexus-claude-plugin/hooks/pre-tool-use.sh  | 78 -------------------
 gitnexus-claude-plugin/hooks/session-start.js | 41 ----------
 gitnexus-claude-plugin/hooks/session-start.sh | 42 ----------
 .../skills/debugging/mcp.json                 |  8 ++
 .../skills/exploring/mcp.json                 |  8 ++
 gitnexus-claude-plugin/skills/guide/SKILL.md  | 63 +++++++++++++++
 gitnexus-claude-plugin/skills/guide/mcp.json  |  8 ++
 .../skills/impact-analysis/mcp.json           |  8 ++
 .../skills/refactoring/mcp.json               |  8 ++
 gitnexus/skills/guide.md                      | 63 +++++++++++++++
 gitnexus/src/cli/ai-context.ts                | 44 ++---------
 gitnexus/src/cli/setup.ts                     |  2 +-
 15 files changed, 215 insertions(+), 211 deletions(-)
 create mode 100644 gitnexus-claude-plugin/.mcp.json
 delete mode 100644 gitnexus-claude-plugin/hooks/pre-tool-use.sh
 delete mode 100644 gitnexus-claude-plugin/hooks/session-start.js
 delete mode 100644 gitnexus-claude-plugin/hooks/session-start.sh
 create mode 100644 gitnexus-claude-plugin/skills/debugging/mcp.json
 create mode 100644 gitnexus-claude-plugin/skills/exploring/mcp.json
 create mode 100644 gitnexus-claude-plugin/skills/guide/SKILL.md
 create mode 100644 gitnexus-claude-plugin/skills/guide/mcp.json
 create mode 100644 gitnexus-claude-plugin/skills/impact-analysis/mcp.json
 create mode 100644 gitnexus-claude-plugin/skills/refactoring/mcp.json
 create mode 100644 gitnexus/skills/guide.md

diff --git a/gitnexus-claude-plugin/.claude-plugin/plugin.json b/gitnexus-claude-plugin/.claude-plugin/plugin.json
index 0772c90dfc..53c40174ef 100644
--- a/gitnexus-claude-plugin/.claude-plugin/plugin.json
+++ b/gitnexus-claude-plugin/.claude-plugin/plugin.json
@@ -1,10 +1,13 @@
 {
   "name": "gitnexus",
   "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
-  "version": "1.0.0",
+  "version": "1.2.8",
   "author": {
     "name": "GitNexus"
   },
   "homepage": "https://github.com/nicosxt/gitnexus",
-  "repository": "https://github.com/nicosxt/gitnexus"
+  "repository": "https://github.com/nicosxt/gitnexus",
+  "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis"],
+  "hooks": "./hooks",
+  "mcpServers": "./.mcp.json"
 }
diff --git a/gitnexus-claude-plugin/.mcp.json b/gitnexus-claude-plugin/.mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus-claude-plugin/hooks/gitnexus-hook.js b/gitnexus-claude-plugin/hooks/gitnexus-hook.js
index 67c890ff5b..53380806b2 100644
--- a/gitnexus-claude-plugin/hooks/gitnexus-hook.js
+++ b/gitnexus-claude-plugin/hooks/gitnexus-hook.js
@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 /**
- * GitNexus Claude Code Hook
+ * GitNexus Claude Code Plugin Hook
  *
  * PreToolUse handler — intercepts Grep/Glob/Bash searches
  * and augments with graph context from the GitNexus index.
  *
- * NOTE: SessionStart hooks are broken on Windows (Claude Code bug).
+ * NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
  * Session context is injected via CLAUDE.md / skills instead.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
+const { spawnSync } = require('child_process');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -101,11 +101,33 @@ function main() {
     const pattern = extractPattern(toolName, toolInput);
     if (!pattern || pattern.length < 3) return;
 
-    const result = execFileSync(
-      'gitnexus',
-      ['augment', pattern],
-      { encoding: 'utf-8', timeout: 8000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
-    );
+    // augment CLI writes result to stderr (KuzuDB's native module captures
+    // stdout fd at OS level, making it unusable in subprocess contexts).
+    let result = '';
+
+    // Try direct gitnexus binary first (faster if globally installed)
+    try {
+      const child = spawnSync(
+        'gitnexus',
+        ['augment', pattern],
+        { encoding: 'utf-8', timeout: 8000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      if (child.status === 0 || (child.stderr && child.stderr.trim())) {
+        result = child.stderr || '';
+      }
+    } catch { /* not on PATH */ }
+
+    // Fallback to npx if direct binary didn't produce output
+    if (!result || !result.trim()) {
+      try {
+        const child = spawnSync(
+          'npx',
+          ['-y', 'gitnexus', 'augment', pattern],
+          { encoding: 'utf-8', timeout: 15000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        result = child.stderr || '';
+      } catch { /* graceful failure */ }
+    }
 
     if (result && result.trim()) {
       console.log(JSON.stringify({
diff --git a/gitnexus-claude-plugin/hooks/pre-tool-use.sh b/gitnexus-claude-plugin/hooks/pre-tool-use.sh
deleted file mode 100644
index 3c1af3bc0c..0000000000
--- a/gitnexus-claude-plugin/hooks/pre-tool-use.sh
+++ /dev/null
@@ -1,78 +0,0 @@
-#!/bin/bash
-# GitNexus PreToolUse hook for Claude Code
-# Intercepts Grep/Glob/Bash searches and augments with graph context.
-# Receives JSON on stdin with { tool_name, tool_input, cwd, ... }
-# Returns JSON with additionalContext for graph-enriched results.
-
-INPUT=$(cat)
-
-TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
-CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
-
-# Extract search pattern based on tool type
-PATTERN=""
-
-case "$TOOL_NAME" in
-  Grep)
-    PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
-    ;;
-  Glob)
-    # Glob patterns are file paths, not search terms — extract meaningful part
-    RAW=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty' 2>/dev/null)
-    # Strip glob syntax to get the meaningful name (e.g., "**/*.ts" → skip, "auth*.ts" → "auth")
-    PATTERN=$(echo "$RAW" | sed -n 's/.*[*\/]\([a-zA-Z][a-zA-Z0-9_-]*\).*/\1/p')
-    ;;
-  Bash)
-    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
-    # Only augment grep/rg commands
-    if echo "$CMD" | grep -qE '\brg\b|\bgrep\b'; then
-      # Extract pattern from rg/grep
-      if echo "$CMD" | grep -qE '\brg\b'; then
-        PATTERN=$(echo "$CMD" | sed -n "s/.*\brg\s\+\(--[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
-      elif echo "$CMD" | grep -qE '\bgrep\b'; then
-        PATTERN=$(echo "$CMD" | sed -n "s/.*\bgrep\s\+\(-[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
-      fi
-    fi
-    ;;
-  *)
-    # Not a search tool — skip
-    exit 0
-    ;;
-esac
-
-# Skip if pattern too short or empty
-if [ -z "$PATTERN" ] || [ ${#PATTERN} -lt 3 ]; then
-  exit 0
-fi
-
-# Check if we're in a GitNexus-indexed repo
-dir="${CWD:-$PWD}"
-found=false
-for i in 1 2 3 4 5; do
-  if [ -d "$dir/.gitnexus" ]; then
-    found=true
-    break
-  fi
-  parent="$(dirname "$dir")"
-  [ "$parent" = "$dir" ] && break
-  dir="$parent"
-done
-
-if [ "$found" = false ]; then
-  exit 0
-fi
-
-# Run gitnexus augment — must be fast (<500ms target)
-RESULT=$(cd "$CWD" && npx -y gitnexus augment "$PATTERN" 2>/dev/null)
-
-if [ -n "$RESULT" ]; then
-  ESCAPED=$(echo "$RESULT" | jq -Rs .)
-  jq -n --argjson ctx "$ESCAPED" '{
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: $ctx
-    }
-  }'
-else
-  exit 0
-fi
diff --git a/gitnexus-claude-plugin/hooks/session-start.js b/gitnexus-claude-plugin/hooks/session-start.js
deleted file mode 100644
index 86157d3545..0000000000
--- a/gitnexus-claude-plugin/hooks/session-start.js
+++ /dev/null
@@ -1,41 +0,0 @@
-// GitNexus SessionStart hook for Claude Code
-// Fires on session startup. Stdout is injected into Claude's context.
-// Checks if the current directory has a GitNexus index.
-
-const fs = require('fs');
-const path = require('path');
-
-let dir = process.cwd();
-let found = false;
-for (let i = 0; i < 5; i++) {
-  if (fs.existsSync(path.join(dir, '.gitnexus'))) {
-    found = true;
-    break;
-  }
-  const parent = path.dirname(dir);
-  if (parent === dir) break;
-  dir = parent;
-}
-
-if (!found) {
-  process.exit(0);
-}
-
-process.stdout.write(`## GitNexus Code Intelligence
-
-This codebase is indexed by GitNexus, providing a knowledge graph with execution flows, relationships, and semantic search.
-
-**Available MCP Tools:**
-- \`query\` — Process-grouped code intelligence (execution flows related to a concept)
-- \`context\` — 360-degree symbol view (categorized refs, process participation)
-- \`impact\` — Blast radius analysis (what breaks if you change a symbol)
-- \`detect_changes\` — Git-diff impact analysis (what do your changes affect)
-- \`rename\` — Multi-file coordinated rename with confidence tags
-- \`cypher\` — Raw graph queries
-- \`list_repos\` — Discover indexed repos
-
-**Quick Start:** READ \`gitnexus://repo/{name}/context\` for codebase overview, then use \`query\` to find execution flows.
-
-**Resources:** \`gitnexus://repo/{name}/context\` (overview), \`/processes\` (execution flows), \`/schema\` (for Cypher)
-`);
-process.exit(0);
diff --git a/gitnexus-claude-plugin/hooks/session-start.sh b/gitnexus-claude-plugin/hooks/session-start.sh
deleted file mode 100644
index 8960dd376d..0000000000
--- a/gitnexus-claude-plugin/hooks/session-start.sh
+++ /dev/null
@@ -1,42 +0,0 @@
-#!/bin/bash
-# GitNexus SessionStart hook for Claude Code
-# Fires on session startup. Stdout is injected into Claude's context.
-# Checks if the current directory has a GitNexus index.
-
-dir="$PWD"
-found=false
-for i in 1 2 3 4 5; do
-  if [ -d "$dir/.gitnexus" ]; then
-    found=true
-    break
-  fi
-  parent="$(dirname "$dir")"
-  [ "$parent" = "$dir" ] && break
-  dir="$parent"
-done
-
-if [ "$found" = false ]; then
-  exit 0
-fi
-
-# Inject GitNexus context — this stdout goes directly into Claude's context
-cat << 'EOF'
-## GitNexus Code Intelligence
-
-This codebase is indexed by GitNexus, providing a knowledge graph with execution flows, relationships, and semantic search.
-
-**Available MCP Tools:**
-- `query` — Process-grouped code intelligence (execution flows related to a concept)
-- `context` — 360-degree symbol view (categorized refs, process participation)
-- `impact` — Blast radius analysis (what breaks if you change a symbol)
-- `detect_changes` — Git-diff impact analysis (what do your changes affect)
-- `rename` — Multi-file coordinated rename with confidence tags
-- `cypher` — Raw graph queries
-- `list_repos` — Discover indexed repos
-
-**Quick Start:** READ `gitnexus://repo/{name}/context` for codebase overview, then use `query` to find execution flows.
-
-**Resources:** `gitnexus://repo/{name}/context` (overview), `/processes` (execution flows), `/schema` (for Cypher)
-EOF
-
-exit 0
diff --git a/gitnexus-claude-plugin/skills/debugging/mcp.json b/gitnexus-claude-plugin/skills/debugging/mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/debugging/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus-claude-plugin/skills/exploring/mcp.json b/gitnexus-claude-plugin/skills/exploring/mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/exploring/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus-claude-plugin/skills/guide/SKILL.md b/gitnexus-claude-plugin/skills/guide/SKILL.md
new file mode 100644
index 0000000000..a069af6e76
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/guide/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: gitnexus-guide
+description: GitNexus quickstart — tools, resources, schema, and workflow reference
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task | Skill to read |
+|------|---------------|
+| Understand architecture / "How does X work?" | `exploring` |
+| Blast radius / "What breaks if I change X?" | `impact-analysis` |
+| Trace bugs / "Why is X failing?" | `debugging` |
+| Rename / extract / split / refactor | `refactoring` |
+| Tools, resources, schema reference | `guide` (this file) |
+
+## Tools Reference
+
+| Tool | What it gives you |
+|------|-------------------|
+| `query` | Process-grouped code intelligence — execution flows related to a concept |
+| `context` | 360-degree symbol view — categorized refs, processes it participates in |
+| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
+| `detect_changes` | Git-diff impact — what do your current changes affect |
+| `rename` | Multi-file coordinated rename with confidence-tagged edits |
+| `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
+| `list_repos` | Discover indexed repos |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource | Content |
+|----------|---------|
+| `gitnexus://repo/{name}/context` | Stats, staleness check |
+| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members |
+| `gitnexus://repo/{name}/processes` | All execution flows |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace |
+| `gitnexus://repo/{name}/schema` | Graph schema for Cypher |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```
diff --git a/gitnexus-claude-plugin/skills/guide/mcp.json b/gitnexus-claude-plugin/skills/guide/mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/guide/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus-claude-plugin/skills/impact-analysis/mcp.json b/gitnexus-claude-plugin/skills/impact-analysis/mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/impact-analysis/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus-claude-plugin/skills/refactoring/mcp.json b/gitnexus-claude-plugin/skills/refactoring/mcp.json
new file mode 100644
index 0000000000..cd02d4285a
--- /dev/null
+++ b/gitnexus-claude-plugin/skills/refactoring/mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
diff --git a/gitnexus/skills/guide.md b/gitnexus/skills/guide.md
new file mode 100644
index 0000000000..a069af6e76
--- /dev/null
+++ b/gitnexus/skills/guide.md
@@ -0,0 +1,63 @@
+---
+name: gitnexus-guide
+description: GitNexus quickstart — tools, resources, schema, and workflow reference
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task | Skill to read |
+|------|---------------|
+| Understand architecture / "How does X work?" | `exploring` |
+| Blast radius / "What breaks if I change X?" | `impact-analysis` |
+| Trace bugs / "Why is X failing?" | `debugging` |
+| Rename / extract / split / refactor | `refactoring` |
+| Tools, resources, schema reference | `guide` (this file) |
+
+## Tools Reference
+
+| Tool | What it gives you |
+|------|-------------------|
+| `query` | Process-grouped code intelligence — execution flows related to a concept |
+| `context` | 360-degree symbol view — categorized refs, processes it participates in |
+| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
+| `detect_changes` | Git-diff impact — what do your current changes affect |
+| `rename` | Multi-file coordinated rename with confidence-tagged edits |
+| `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
+| `list_repos` | Discover indexed repos |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource | Content |
+|----------|---------|
+| `gitnexus://repo/{name}/context` | Stats, staleness check |
+| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members |
+| `gitnexus://repo/{name}/processes` | All execution flows |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace |
+| `gitnexus://repo/{name}/schema` | Graph schema for Cypher |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```
diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts
index 6f8d1ede6f..ebb0ac56fe 100644
--- a/gitnexus/src/cli/ai-context.ts
+++ b/gitnexus/src/cli/ai-context.ts
@@ -42,12 +42,8 @@ function generateGitNexusContent(projectName: string, stats: RepoStats): string
 
 This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
 
-GitNexus provides a knowledge graph over this codebase — call chains, blast radius, execution flows, and semantic search.
-
 ## Always Start Here
 
-For any task involving code understanding, debugging, impact analysis, or refactoring, you must:
-
 1. **Read \`gitnexus://repo/{name}/context\`** — codebase overview + check index freshness
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
@@ -62,41 +58,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/impact-analysis/SKILL.md\` |
 | Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/debugging/SKILL.md\` |
 | Rename / extract / split / refactor | \`.claude/skills/gitnexus/refactoring/SKILL.md\` |
-
-## Tools Reference
-
-| Tool | What it gives you |
-|------|-------------------|
-| \`query\` | Process-grouped code intelligence — execution flows related to a concept |
-| \`context\` | 360-degree symbol view — categorized refs, processes it participates in |
-| \`impact\` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
-| \`detect_changes\` | Git-diff impact — what do your current changes affect |
-| \`rename\` | Multi-file coordinated rename with confidence-tagged edits |
-| \`cypher\` | Raw graph queries (read \`gitnexus://repo/{name}/schema\` first) |
-| \`list_repos\` | Discover indexed repos |
-
-## Resources Reference
-
-Lightweight reads (~100-500 tokens) for navigation:
-
-| Resource | Content |
-|----------|---------|
-| \`gitnexus://repo/{name}/context\` | Stats, staleness check |
-| \`gitnexus://repo/{name}/clusters\` | All functional areas with cohesion scores |
-| \`gitnexus://repo/{name}/cluster/{clusterName}\` | Area members |
-| \`gitnexus://repo/{name}/processes\` | All execution flows |
-| \`gitnexus://repo/{name}/process/{processName}\` | Step-by-step trace |
-| \`gitnexus://repo/{name}/schema\` | Graph schema for Cypher |
-
-## Graph Schema
-
-**Nodes:** File, Function, Class, Interface, Method, Community, Process
-**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
-
-\`\`\`cypher
-MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
-RETURN caller.name, caller.filePath
-\`\`\`
+| Tools, resources, schema reference | \`.claude/skills/gitnexus/guide/SKILL.md\` |
 
 ${GITNEXUS_END_MARKER}`;
 }
@@ -178,6 +140,10 @@ async function installSkills(repoPath: string): Promise<string[]> {
       name: 'refactoring',
       description: 'Plan safe refactors using blast radius and dependency mapping',
     },
+    {
+      name: 'guide',
+      description: 'GitNexus quickstart — tools, resources, schema, and workflow reference',
+    },
   ];
 
   for (const skill of skills) {
diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts
index 77515a49a8..34554ce473 100644
--- a/gitnexus/src/cli/setup.ts
+++ b/gitnexus/src/cli/setup.ts
@@ -217,7 +217,7 @@ async function setupOpenCode(result: SetupResult): Promise<void> {
 
 // ─── Skill Installation ───────────────────────────────────────────
 
-const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring'];
+const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring', 'guide'];
 
 /**
  * Install GitNexus skills to a target directory.