Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
feat(skill): add /understand-onboard command for team onboarding guides
Lum110409fc78f32168
diff --git a/packages/skill/.claude/skills/understand-onboard.md b/packages/skill/.claude/skills/understand-onboard.mdnew file mode 100644index 00000000..873a1b9b--- /dev/null+++ b/packages/skill/.claude/skills/understand-onboard.md@@ -0,0 +1,23 @@+---+name: understand-onboard+description: Generate a structured onboarding guide for new team members using the knowledge graph+---++# /understand-onboard++Generate a comprehensive onboarding guide from the project's knowledge graph.++## Instructions++1. Read the knowledge graph at `.understand-anything/knowledge-graph.json`+2. If it doesn't exist, tell the user to run `/understand` first+3. Generate a structured onboarding guide that includes:+ - Project overview (name, languages, frameworks, description)+ - Architecture layers and their responsibilities+ - Key concepts to understand+ - Guided tour (step-by-step walkthrough)+ - File map (what each key file does)+ - Complexity hotspots (what to be careful with)+4. Format as clean markdown+5. Offer to save the guide to `docs/ONBOARDING.md` in the project+6. Suggest the user commit it to the repo for the teamdiff --git a/packages/skill/src/__tests__/onboard-builder.test.ts b/packages/skill/src/__tests__/onboard-builder.test.tsnew file mode 100644index 00000000..4408b11a--- /dev/null+++ b/packages/skill/src/__tests__/onboard-builder.test.ts@@ -0,0 +1,87 @@+import { describe, it, expect } from "vitest";+import { buildOnboardingGuide } from "../onboard-builder.js";+import type { KnowledgeGraph } from "@understand-anything/core";++const sampleGraph: KnowledgeGraph = {+ version: "1.0.0",+ project: {+ name: "test-project",+ languages: ["typescript", "python"],+ frameworks: ["express", "prisma"],+ description: "A test REST API",+ analyzedAt: "2026-03-14T00:00:00Z",+ gitCommitHash: "abc123",+ },+ nodes: [+ { id: "file:src/index.ts", type: "file", name: "index.ts", filePath: "src/index.ts", summary: "Entry point", tags: ["entry"], complexity: "simple" },+ { id: "file:src/service.ts", type: "file", name: "service.ts", filePath: "src/service.ts", summary: "Core service", tags: ["service"], complexity: "complex" },+ { id: "concept:auth", type: "concept", name: "Auth Flow", summary: "JWT-based authentication", tags: ["concept", "auth"], complexity: "complex" },+ ],+ edges: [+ { source: "file:src/index.ts", target: "file:src/service.ts", type: "imports", direction: "forward", weight: 0.8 },+ ],+ layers: [+ { id: "layer:api", name: "API Layer", description: "Routes and handlers", nodeIds: ["file:src/index.ts"] },+ { id: "layer:service", name: "Service Layer", description: "Business logic", nodeIds: ["file:src/service.ts"] },+ ],+ tour: [+ { order: 1, title: "Start Here", description: "Begin with index.ts", nodeIds: ["file:src/index.ts"] },+ { order: 2, title: "Core Logic", description: "Service layer", nodeIds: ["file:src/service.ts"] },+ ],+};++describe("onboard-builder", () => {+ it("includes project overview section", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("# test-project");+ expect(guide).toContain("A test REST API");+ });++ it("lists languages and frameworks", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("typescript");+ expect(guide).toContain("express");+ });++ it("includes architecture layers section", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("## Architecture");+ expect(guide).toContain("API Layer");+ expect(guide).toContain("Service Layer");+ });++ it("includes key concepts section", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("## Key Concepts");+ expect(guide).toContain("Auth Flow");+ });++ it("includes getting started / tour section", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("## Getting Started");+ expect(guide).toContain("Start Here");+ });++ it("includes complexity hotspots", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("## Complexity Hotspots");+ expect(guide).toContain("service.ts");+ });++ it("includes file map section", () => {+ const guide = buildOnboardingGuide(sampleGraph);+ expect(guide).toContain("## File Map");+ });++ it("handles graph with no layers gracefully", () => {+ const noLayers = { ...sampleGraph, layers: [] };+ const guide = buildOnboardingGuide(noLayers);+ expect(guide).toContain("# test-project");+ });++ it("handles graph with no tour gracefully", () => {+ const noTour = { ...sampleGraph, tour: [] };+ const guide = buildOnboardingGuide(noTour);+ expect(guide).toContain("# test-project");+ });+});diff --git a/packages/skill/src/index.ts b/packages/skill/src/index.tsindex d9bbcac3..c0526d3c 100644--- a/packages/skill/src/index.ts+++ b/packages/skill/src/index.ts@@ -14,3 +14,4 @@ export {formatExplainPrompt,type ExplainContext,} from "./explain-builder.js";+export { buildOnboardingGuide } from "./onboard-builder.js";diff --git a/packages/skill/src/onboard-builder.ts b/packages/skill/src/onboard-builder.tsnew file mode 100644index 00000000..ed794455--- /dev/null+++ b/packages/skill/src/onboard-builder.ts@@ -0,0 +1,124 @@+import type { KnowledgeGraph } from "@understand-anything/core";++/**+ * Generate a structured onboarding guide from the knowledge graph.+ * Output is standalone markdown suitable for a README, wiki, or docs.+ */+export function buildOnboardingGuide(graph: KnowledgeGraph): string {+ const { project, nodes, edges, layers, tour } = graph;+ const lines: string[] = [];++ // --- Project Overview ---+ lines.push(`# ${project.name}`);+ lines.push("");+ lines.push(`> ${project.description}`);+ lines.push("");+ lines.push(`| | |`);+ lines.push(`|---|---|`);+ lines.push(`| **Languages** | ${project.languages.join(", ")} |`);+ lines.push(`| **Frameworks** | ${project.frameworks.join(", ")} |`);+ lines.push(`| **Components** | ${nodes.length} nodes, ${edges.length} relationships |`);+ lines.push(`| **Last Analyzed** | ${project.analyzedAt} |`);+ lines.push("");++ // --- Architecture ---+ if (layers.length > 0) {+ lines.push("## Architecture");+ lines.push("");+ lines.push("The project is organized into the following layers:");+ lines.push("");++ for (const layer of layers) {+ const memberNames = layer.nodeIds+ .map((id) => nodes.find((n) => n.id === id)?.name)+ .filter(Boolean);+ lines.push(`### ${layer.name}`);+ lines.push("");+ lines.push(layer.description);+ lines.push("");+ if (memberNames.length > 0) {+ lines.push(`Key components: ${memberNames.join(", ")}`);+ lines.push("");+ }+ }+ }++ // --- Key Concepts ---+ const conceptNodes = nodes.filter((n) => n.type === "concept");+ if (conceptNodes.length > 0) {+ lines.push("## Key Concepts");+ lines.push("");+ lines.push("Important architectural and domain concepts to understand:");+ lines.push("");+ for (const concept of conceptNodes) {+ lines.push(`### ${concept.name}`);+ lines.push("");+ lines.push(concept.summary);+ lines.push("");+ }+ }++ // --- Getting Started (Tour) ---+ if (tour.length > 0) {+ lines.push("## Getting Started");+ lines.push("");+ lines.push("Follow this guided tour to understand the codebase:");+ lines.push("");+ for (const step of tour) {+ const stepNodes = step.nodeIds+ .map((id) => nodes.find((n) => n.id === id))+ .filter(Boolean);+ lines.push(`### ${step.order}. ${step.title}`);+ lines.push("");+ lines.push(step.description);+ lines.push("");+ if (stepNodes.length > 0) {+ lines.push("**Files to look at:**");+ for (const node of stepNodes) {+ if (node!.filePath) {+ lines.push(`- \`${node!.filePath}\` — ${node!.summary}`);+ }+ }+ lines.push("");+ }+ if (step.languageLesson) {+ lines.push(`> **Language Tip:** ${step.languageLesson}`);+ lines.push("");+ }+ }+ }++ // --- File Map ---+ const fileNodes = nodes.filter((n) => n.type === "file" && n.filePath);+ if (fileNodes.length > 0) {+ lines.push("## File Map");+ lines.push("");+ lines.push("| File | Purpose | Complexity |");+ lines.push("|------|---------|------------|");+ for (const node of fileNodes) {+ lines.push(`| \`${node.filePath}\` | ${node.summary} | ${node.complexity} |`);+ }+ lines.push("");+ }++ // --- Complexity Hotspots ---+ const complexNodes = nodes.filter((n) => n.complexity === "complex");+ if (complexNodes.length > 0) {+ lines.push("## Complexity Hotspots");+ lines.push("");+ lines.push("These components are the most complex and deserve extra attention:");+ lines.push("");+ for (const node of complexNodes) {+ lines.push(`- **${node.name}** (${node.type}): ${node.summary}`);+ }+ lines.push("");+ }++ // --- Footer ---+ lines.push("---");+ lines.push("");+ lines.push(`*Generated by [Understand Anything](https://github.com/anthropics/understand-anything) from knowledge graph v${graph.version}*`);+ lines.push("");++ return lines.join("\n");+}