alekspetrov/navigator/nav-graph

Name: nav-graph
Author: alekspetrov

Claude Code and agent skill by alekspetrov/navigator

Trust tier 2

community

Source check pending

Checking that the SKILL.md file is still in the repository.

Query project knowledge graph. Search across tasks, SOPs, memories, and concepts. Use when user asks "what do we know about X?", "show everything related to X", or "remember this pattern/pitfall/decision".

Install

npx vskill@latest install alekspetrov/navigator/nav-graph

SKILL.md

Navigator Knowledge Graph Skill

Query and manage the unified project knowledge graph. Surfaces relevant knowledge from tasks, SOPs, system docs, and experiential memories.

Why This Exists

Navigator v6.0.0 introduces the Project Knowledge Graph:

Unified search: Query across all knowledge types with one interface
Experiential memory: Patterns, pitfalls, decisions, learnings persist
Context-aware retrieval: Load only relevant knowledge (~1-2k tokens)
Relationship traversal: Find related concepts and documents

When to Invoke

Query triggers:

"What do we know about X?"
"Show everything related to X"
"Any pitfalls for X?"
"What decisions about X?"
"Find all knowledge about X"

Memory capture triggers:

"Remember this pattern: ..."
"Remember this pitfall: ..."
"Remember we decided: ..."
"Remember this learning: ..."

Graph management triggers:

"Initialize knowledge graph"
"Rebuild knowledge graph"
"Show graph stats"

Graph Location

.agent/knowledge/graph.json (~1-2k tokens, loaded on query)

Execution Steps

Step 1: Determine Action

QUERY (searching knowledge):

User: "What do we know about authentication?"
→ Query graph by concept

CAPTURE (storing memory):

User: "Remember: auth changes often break session tests"
→ Create new memory node

INIT (building graph):

User: "Initialize knowledge graph"
→ Build graph from existing docs

STATS (viewing graph):

User: "Show graph stats"
→ Display graph statistics

Step 2: Load or Initialize Graph

Check if graph exists:

bash

if [ -f ".agent/knowledge/graph.json" ]; then
  echo "Graph exists"
else
  echo "No graph found, will initialize"
fi

Initialize if not exists:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_builder.py" \
  --agent-dir .agent \
  --output .agent/knowledge/graph.json

Step 3A: Query Knowledge (If QUERY Action)

Extract concept from user input:

User: "What do we know about testing?"
→ Concept: testing
 
User: "Any pitfalls for auth?"
→ Concept: auth (normalized to authentication)

Run query:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action query \
  --concept "testing" \
  --graph-path .agent/knowledge/graph.json

Display results:

Knowledge Graph: "testing"
 
TASKS (3)
  - TASK-30: Task Verification Enhancement (completed)
  - TASK-17: Visual Regression Integration (completed)
  - TASK-11: Project Skills Generation (completed)
 
MEMORIES (2)
  - PITFALL: "Auth changes break session tests" (90%)
  - PATTERN: "Always run unit tests before integration" (85%)
 
SOPs (1)
  - visual-regression-setup
 
FILES (5)
  - skills/backend-test/*
  - skills/frontend-test/*
 
Load details: "Read TASK-30" or "Show testing memories"

Step 3B: Capture Memory (If CAPTURE Action)

Parse memory from user input:

User: "Remember this pitfall: auth changes often break session tests"
→ Type: pitfall
→ Summary: "auth changes often break session tests"
→ Concepts: [auth, testing]
 
User: "Remember we decided to use JWT over sessions for scaling"
→ Type: decision
→ Summary: "use JWT over sessions for scaling"
→ Concepts: [auth, architecture]

Determine memory type:

User Says	Memory Type
"pattern", "we use", "approach"	pattern
"pitfall", "watch out", "careful"	pitfall
"decided", "chose", "because"	decision
"learned", "discovered", "realized"	learning

Create memory:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action add-memory \
  --memory-type pitfall \
  --summary "auth changes often break session tests" \
  --concepts "auth,testing" \
  --confidence 0.9 \
  --graph-path .agent/knowledge/graph.json

Write guarantees (v6.17.0+): the backing .md is written BEFORE the graph node and failures fail loudly (no more path-points-at-nothing nodes); a failed graph save rolls the file back. Concepts are validated against the graph's concept vocabulary — an unknown concept rejects the write and lists the valid vocabulary. Pass --allow-new-concept to register genuinely new concepts instead. Graphs without a curated vocabulary skip validation.

Decisions may carry a TRIZ contradiction (TASK-72). When a decision resolved a real tension (improving A worsened B), record it so future sessions can ask "how did we resolve this kind of problem before":

bash

python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action add-memory --memory-type decision \
  --summary "ship new blocking features OFF by default" \
  --concepts "release,configuration" --confidence 0.95 \
  --contradiction "feature value vs regression risk" \
  --separation condition \
  --principle "dynamization (config toggle)"

All three flags are optional and free text; keep --contradiction under ~60 chars ("A vs B") because it is appended to recall lines. Separation modes (which TRIZ move resolved it):

Separation	Meaning	Software example
time	A now, B later	re-export shims for one major, delete next (mem-063)
space	A here, B there	single redacting emitter module; ops never print (mem-065)
condition	A when X, B otherwise	confirm + dry-run only on high-stakes dispatch (mem-043)
level	A at part level, B at system level	atomic tmp+rename state file over per-op writes (mem-064)

Query by contradiction (every filter word must match, case-insensitive, across contradiction + summary + principle; always exits 0):

bash

python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action contradictions --filter "rollback"
# Contradictions "rollback" (2)
#   - DECISION: "..." (95%) ↔ clean codebase vs rollback safety [separation: time]
#       principle: prior counter-action

Tagged memories also render with a ↔ A vs B suffix in session-start and nav-brief recall. Hand-tagging an existing decision = append the three footer lines after **Concepts**: in its .md, then graph_maintenance.py --action reconcile --execute --fields-only (see Reconcile below; --fields-only keeps a pruned resolved/ archive from being re-registered under fresh ids).

Optionally create detailed memory file:

markdown

# Pitfall: Auth Changes Break Session Tests
 
## Summary
Auth changes often break session tests due to...
 
## Context
Discovered during TASK-XX when...
 
## Recommended Approach
When modifying auth, always run...
 
## Related
-TASK-12: V3 Skills-Only
-SOP: autonomous-completion

Confirm capture:

Memory captured: mem-001
 
Type: Pitfall
Summary: "auth changes often break session tests"
Concepts: auth, testing
Confidence: 90%
 
This will be surfaced when working on auth or testing topics.

Step 3C: Initialize Graph (If INIT Action)

Build from existing docs:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_builder.py" \
  --agent-dir .agent \
  --output .agent/knowledge/graph.json

Display results:

Knowledge Graph Initialized
 
Scanned:
  - Tasks: 35
  - SOPs: 12
  - System docs: 3
  - Markers: 8
 
Extracted:
  - Concepts: 15
  - Relationships: 47
 
Graph saved to .agent/knowledge/graph.json
 
Query with: "What do we know about [topic]?"

Rebuild safety (v6.17.0+): re-running the builder over an existing graph PRESERVES the memories and files buckets and their edges — memories carry graph-only fields no scan can reconstruct, and rebuilds used to wipe them silently. Pass --no-preserve-memories for an intentional from-scratch rebuild.

Step 3D: Show Stats (If STATS Action)

Display graph statistics:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action stats \
  --graph-path .agent/knowledge/graph.json

Output:

Knowledge Graph Statistics
==========================
Total Nodes: 65
Total Edges: 47
Memories: 5
Last Updated: 2025-01-23T10:30:00Z
 
By Type:
  Tasks: 35
  SOPs: 12
  System: 3
  Markers: 8
  Concepts: 15
  Memories: 5

Step 4: Find Related (Optional)

If user asks for related items:

User: "What's related to TASK-29?"

Run traversal:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action related \
  --node-id "TASK-29" \
  --max-depth 2 \
  --graph-path .agent/knowledge/graph.json

Memory Types

Pattern

"We use X for Y in this project"

Reusable approaches
Project conventions
Best practices

Pitfall

"Watch out for X when touching Y"

Common mistakes
Gotchas
Failure modes

Decision

"We chose X over Y because Z"

Architecture decisions
Technology choices
Trade-off rationale

Learning

"X usually means Y in this codebase"

Project-specific knowledge
Error interpretations
Domain insights

Confidence System

Base confidence:

Correction-based: 0.8
Explicit capture: 0.9

Decay:

1% per week since last validation

Boost:

+5% per use (max +25%)

Threshold:

Below 0.3: Candidate for pruning
Above 0.7: Reliable memory

Integration with Other Skills

nav-start (Session Start)

Loads graph stats on session start:

Knowledge graph: 65 nodes, 5 memories
Relevant: 2 memories for current context

nav-task (Task Creation)

Auto-extracts concepts from new tasks:

Creating TASK-35: Project Memory
Extracted concepts: knowledge, memory, graph
Added to graph.

nav-profile (Corrections)

Corrections auto-create memories via correction_to_memory.py:

bash

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
# When correction detected in nav-profile:
python3 "$PLUGIN_DIR/skills/nav-graph/functions/correction_to_memory.py" \
  --action convert-one \
  --correction-json '{"pattern": "...", "context": "...", "confidence": "high"}'
 
# Output:
[Correction detected]
→ Type: pitfall (based on pattern analysis)
→ Concepts: [auth, testing] (auto-extracted)
→ Created memory: mem-002
→ Added to graph

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/nav-graph/SKILL.md

Popularity

Repository stars: 161
Repository forks: 8
7-day trend score: 25

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 1 Apr 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/alekspetrov/navigator/nav-graph/badge)](https://verified-skill.com/skills/alekspetrov/navigator/nav-graph)

Something wrong with this skill or its page? Tell us.