personal-knowledge-graph-builder

name

personal-knowledge-graph-builder

description

Build a complete compounding knowledge base — folder scaffold, Google Sheet mirror, 3D interactive knowledge graph artifact, Cowork sidebar companion, daily/weekly scheduled tasks. Uses PubMed MCP, WebSearch, and Google Drive with grounding rules derived from actual build failures. Triggers on "build me a knowledge graph for", "create a new knowledge base", "build a personal reader's digest", "compounding context system", "build a reading database", "set up a daily curated reading list", "make me a [topic] research dashboard", or any request to set up a new compounding research artifact. Always interview the user about pillars and out-of-scope content before building. CRITICAL — before building, READ references/02-GROUNDING-RULES-FOR-YOUR-CLAUDE.md and references/01-CHALLENGES.md in this skill folder; they document failure modes from actual builds.

Personal Knowledge Graph Builder

Build a compounding knowledge base the user will actually use. The pattern is validated — two prior builds (a Personal Reader's Digest across industry/policy/clinical pillars and an Academic Orthopedic Knowledge Base from ABOS WLA PDFs) prove the architecture works when the failure modes documented in references/ are avoided.

---

STEP ZERO — Read these reference files before doing anything

Before you call any tool to scaffold a folder or write a file, Read these three files from this skill's references/ directory:

1. references/02-GROUNDING-RULES-FOR-YOUR-CLAUDE.md — twelve non-negotiable rules derived from actual build failures. Internalize them.
2. references/01-CHALLENGES.md — the post-mortem. Read at minimum the section headings to understand the failure-mode landscape.
3. references/03-DEBUGGING-CHECKLIST.md — diagnostic order when something breaks. Useful when the user reports issues.

Skipping these means repeating the failures they document — citation hallucinations, silent CDN failures, CSS zero-height bugs, sandbox API surprises, template drift, Sheet ID drift, cross-KB contamination, and more.

---

Pre-flight: confirm required MCPs

Confirm these connectors are connected via Cowork settings. If any required ones are missing, stop and tell the user to connect them before proceeding:

• PubMed MCP (required for clinical/biomedical citations with PMIDs and DOIs)
• Google Drive (required for the Sheet mirror)
• WebSearch (required for industry/news content)
• Gmail (optional but valuable — for scanning newsletters in the user's inbox)

---

Phase 1 — Interview (under 2 minutes)

Ask one at a time:

1. Knowledge base name? Used for folder name. Examples: "JBJS Knowledge Base", "Health Policy KB", "Cardiothoracic Surgery Literature".
2. Three to four pillars? Give an example tied to the KB topic so they can react. Each pillar gets its own slice of every digest.
3. What's out of scope? If this KB overlaps with an existing one, what stays in the other (e.g., academic literature stays in the academic KB, not the personal RD).
4. Cadence? Default daily 6 AM for fast-moving topics (industry, policy). Weekly Mondays for academic literature.
5. PubMed-heavy or WebSearch-heavy? Biases query design.
6. PDF ingestion needed? If yes, scaffold inbox/pdfs/ and add a weekly PDF-ingestion scheduled task.
7. Which Drive account for the Sheet mirror?

---

Phase 2 — Scaffold the folder

Standard structure under the user's chosen workspace root (default: ~/Desktop/Active Work/):

{KB_NAME}/
├── CLAUDE.md
├── README.md
├── interests.md
├── config.json
├── library.json
├── library.csv
├── digests/
├── visualizations/
│   ├── knowledge-graph.html
│   └── cowork-companion.html
├── reading-notes/
│   └── _archive/
├── inbox/
│   └── pdfs/
│       └── _archive/
└── Claude output/

Use the .template files from references/ as the basis for CLAUDE.md, README.md, interests.md, and config.json. Substitute KB-specific values.

---

Phase 3 — Seed library (CRITICAL: real citations only)

Per Rule 1 in references/02-GROUNDING-RULES-FOR-YOUR-CLAUDE.md: every article must be verified. No fabrication.

• For each pillar, find 4-6 real articles via:
  • PubMed MCP for clinical/biomedical content — call search_articles then get_article_metadata to capture real pmid, doi, exact title, journal, authors, abstract
  • WebSearch for industry/policy/news — capture the actual specific article URL from search results (never google.com/search?q=... URLs, never homepages)
• Mark every article with verified_by: "pubmed_mcp", "web_search", or "pdf_ingest"
• Pre-star 2-3 per pillar to seed the weighted_concepts compounding map
• If you cannot find 5 real items for a pillar, ship fewer. Never pad with fabrications.

---

Phase 4 — Create the Google Sheet on Drive

Use the Google Drive MCP create_file tool with contentMimeType: "text/csv" and a clear title (e.g., "JBJS Knowledge Base — Library"). Capture the returned ID and write it to config.json.source_of_truth.sheet_id.

If regenerating an existing KB, log the previous Sheet ID under source_of_truth.previous_sheet_id_to_delete so the user can clean up Drive manually (the Drive MCP has no in-place update endpoint — every regeneration creates a new file).

---

Phase 5 — Build the artifacts FROM THE BUNDLED TEMPLATES

Do not improvise these HTMLs from scratch. Read the templates from this skill's templates/ directory:

• templates/knowledge-graph-template.html — standalone 3D graph (~70KB, opens in browser)
• templates/cowork-companion-template.html — Cowork sidebar artifact (~37KB)

Substitute:

• LIBRARY_JSON_PLACEHOLDER → the seed library JSON object
• Sheet ID references (use sed or Python to replace ALL occurrences of the placeholder ID — don't trust manual find/replace)
• Brand mark in header (2-letter abbreviation of the KB name, e.g., "JK" for JBJS Knowledge)
• Pillar names and colors in CSS variables and JS constants
• Title text, subtitle
• localStorage keys (each KB needs unique keys to avoid collision: prd_mutations_v2, aok_mutations_v1, {kb-slug}_mutations_v1, etc.)
• Path references (replace "Personal Knowledge Base" with the new KB name everywhere — including inside JavaScript strings)

Critical bug fixes already baked into the templates — do not regenerate or "improve" these:

• CSS grid grid-template-rows: 1fr; height: 100%; min-height: 0 on graph container (without these, three.js renders into a 0×0 canvas — silent failure)
• Multi-CDN fallback loader with always-visible status banner (without this, CDN failures are invisible — the most painful failure mode)
• try/catch isolation on every render call in switchTab (without this, one failure cascades to all components)
• applyMutations guard against empty-string localStorage clobbering seed notes
• document.execCommand('copy') fallback for the Cowork sandbox's blocked Clipboard API
• Always-visible readonly path input as bulletproof fallback for "Open 3D graph" action

If you find a bug in a template, fix the bug in the template AND in any live KB that uses it. Template drift is failure mode #6 in CHALLENGES.md.

---

Phase 6 — Register the scheduled tasks

Use mcp__scheduled-tasks__create_scheduled_task twice. Paste the prompts from references/scheduled-task-prompt.md, substituting <KB_FOLDER_PATH> and <SHEET_ID> placeholders.

Standard cadences:

• Daily pull: 0 6 * * * (industry, policy, news)
• Weekly pull: 0 7 * * 1 (academic literature — slower-moving)
• Monthly review: 0 7 1 * * (reflective synthesis)
• PDF ingestion (optional, weekly): 0 8 * * 1

---

Phase 7 — Register the Cowork Live Artifact

Use mcp__cowork__create_artifact with id set to the kebab-case version of the KB name (e.g., jbjs-knowledge-base) pointing at the cowork-companion.html. This gives the user one-click sidebar access.

---

Phase 8 — Pre-flight checklist (must pass before declaring done)

• All required MCPs confirmed connected
• No URL in library.json contains google.com/search or is a generic homepage
• Every PubMed-sourced article has both pmid and doi
• Standalone HTML's 3D graph renders when opened in the user's browser (have them verify)
• Both scheduled tasks registered (verify with mcp__scheduled-tasks__list_scheduled_tasks)
• Cowork Live Artifact registered (verify with mcp__cowork__list_artifacts)
• Sheet exists on the user's Drive and contains all seed rows
• PDF inbox folder exists if PDF ingestion was requested
• localStorage key in HTMLs is unique to this KB (won't collide with other KBs)

---

Phase 9 — Final report

Give the user:

• A computer:// link to the standalone knowledge-graph.html
• A direct link to the Google Sheet on Drive
• Confirmation that both scheduled tasks are registered (by task ID)
• The pre-flight checklist with each item confirmed
• Any open issues

---

Cross-knowledge-base awareness

The user may have multiple parallel knowledge bases. Before adding any content, check:

• Each KB's config.json.scope (or academic_separation.rule in the Personal Reader's Digest)
• Whether the content topic clearly belongs to one KB vs another

If content could land in two places, ask the user before defaulting to "whichever was most recently in conversation."

---

When NOT to use this skill

• One-off literature reviews (no persistent state needed)
• Single-shot research summaries
• Content generation that doesn't involve a knowledge base (newsletter drafts, presentations, etc.)
• Modifying an existing KB (edit directly, don't rebuild from scratch)
• Pure design tweaks ("make it darker") — edit the live HTML in place

---

After-the-fact customization

The user customizes conversationally. They say "darker background" or "add a fourth pillar" and expect in-place edits. Read the current file, apply the diff, save. Don't rebuild from scratch for design changes.

For data changes (new article, retag), edit library.json directly and ask whether to regenerate the Sheet.