Skip to content

dvy1987/agent-loom / .agents/skills/knowledge-graph

knowledge-graph

Flagged

Build, update, and query a persistent project knowledge graph from skills, memory, docs, and code structure — stdlib Python only, no external tools. Dual-mode: skill-library (agent-loom) or application (any consumer repo). Load when the user asks for a knowledge graph, project map, skill relationships, query the graph, update the graph, or trace how components connect. Auto-runs on memory-handoff and project-setup bootstrap. Also triggers on "build the graph", "what connects to X", "map this project".

Knowledge Graph

You maintain a queryable project graph at docs/knowledge-graph/. Stdlib Python only — no Graphify, no pip deps, no external URLs in outputs.

Deployment Context

HostModeTypical use
agent-loom (skill library)skill-libraryMap skill invoke chains, memory, handoffs
Any consumer projectapplicationMap modules, docs, memory for GRAPHIFY-style project management

Mode auto-detects from authoritative skill-library files: docs/skill-graph.md and docs/SKILL-INDEX.md → skill-library label; otherwise application. Both modes always perform a repo-wide scan — skills, all application source (any path), packages, config, docs, memory, directories. Never skills-only.

Hard Rules

  • Full repo, always. build_graph.py walks the entire repository for source files. .agents/skills/ is indexed as skills, not skipped — but application code in packages/, artifacts/, lib/, etc. must appear as module nodes.
  • Query before rebuild. Relational questions → query_graph.py first.
  • Authoritative > inferred. invokes from docs/skill-graph.md + SKILL-INDEX.md Calls: lines are authoritative; references edges are hypotheses.
  • Shrink guard. No --force unless user confirms or graph is corrupt.
  • Handoff sync. Every memory-handoff → --incremental build.
  • No secrets. Skip .env, credentials, tokens by path name.

Common Rationalizations

ExcuseReality
"I'll just grep"Grep misses invoke chains and handoff lineage. Query the graph.
"Graph is stale, full rebuild"Try --incremental first; authoritative sources may be unchanged.
"INFERRED edge = fact"Read source_file / provenance before acting.
"Skip graph on handoff"Next agent loses relational context.
"Need Graphify pip package"Native stdlib scripts; patterns only, no install.
"Only for agent-loom"Bootstrap in every project via project-setup.
"Many skills = skills-only graph"Wrong — repo-wide scan always runs; read build stdout Why: line.

Workflow

Step 1 — Check existing graph

Read GRAPH_INDEX.md and GRAPH_REPORT.md when present.

Step 2 — Build or update

python3 .agents/skills/knowledge-graph/scripts/build_graph.py              # full repo scan
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental  # handoff/default
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --force       # override shrink guard
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --strict      # fail if source on disk but 0 modules

Stdout always prints: auto mode label, why that label was chosen, and scan layers (skills, code dirs, docs, memory). Read it before assuming skills-only — both modes scan the full repository.

Step 3 — Query

python3 .agents/skills/knowledge-graph/scripts/query_graph.py query "memory handoff connections"
python3 .agents/skills/knowledge-graph/scripts/query_graph.py path memory-handoff knowledge-graph
python3 .agents/skills/knowledge-graph/scripts/query_graph.py explain validate-skills

Cite path, confidence, and provenance for every hit. routing_note in JSON output confirms authoritative-first ordering — prefer invokes edges from skill-graph.md over INFERRED heuristics when choosing skills.

Step 4 — Health audit (optional / validate-skills hook)

python3 .agents/skills/knowledge-graph/scripts/graph_health.py

Step 5 — Report

Summarize: mode, node/edge counts, authoritative vs inferred ratio, hub nodes, communities, top query results.


Handoff Hook (mandatory for memory-handoff)

After appending to agent-handoffs.md:

python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental

If build fails, note in handoff ### Graph — do not block save.


Output Format

## Knowledge graph — [full | incremental | query | health]

Mode: [skill-library | application]
Stats: [N] nodes, [E] edges ([A] authoritative invokes)
Hub nodes: [top 3]
Query: "[question]" → [matches with confidence tags]
Files: graph.json, call-graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md

Verification

  • graph.json, GRAPH_INDEX.md, GRAPH_REPORT.md exist under docs/knowledge-graph/
  • Build stdout shows repo-wide source layer (not skills-only)
  • Consumer repos with code have module nodes in graph.json stats
  • call-graph.json present when mode=skill-library
  • Shrink guard respected (or --force approved)
  • Query results cite path + confidence + provenance
  • Handoff hook ran --incremental when invoked from memory-handoff
  • No secrets or external URLs in graph artifacts

Red Flags

  • Full graph rebuild run before query_graph for relational ask
  • Inferred edges override authoritative Calls: from SKILL-INDEX
  • Repo walk skipped — partial graph presented as complete
  • graph.json stale versus latest handoff not rebuilt

Reference Files

  • references/schema.md — node/edge types, provenance priority
  • references/integration.md — producers/consumers, project-setup bootstrap
  • scripts/build_graph.py — full/incremental build
  • scripts/query_graph.py — query, path, explain
  • scripts/graph_health.py — dangling invokes, stale graph, orphan skills

File Output

Append to docs/skill-outputs/SKILL-OUTPUTS.md:

| YYYY-MM-DD HH:MM | knowledge-graph | docs/knowledge-graph/ | [N] nodes, [E] edges, mode=[mode] |

Examples


Prune Log

Last pruned: 2026-07-04

  • No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Knowledge graph: [full/incremental/query/health]
Mode: [skill-library|application] | Nodes: [N] | Edges: [E]
Authoritative invokes: [A] | EXTRACTED: [E] | INFERRED: [I]
Shrink guard: [ok/refused/forced] | Handoff sync: [yes/no]
Consumers notified: [list or n/a]
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall