Compile markdown knowledge files or codebases into a topic-based wiki. Implements Karpathy's LLM Knowledge Base pattern.

version
2.1.0
GitHub stars
331

Install

/plugin install llm-wiki-compiler@llm-wiki-compiler

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ussumant/llm-wiki-compiler.

Contents

Discovered from source

Skills 1

Wiki Compiler — Compilation Algorithm

This skill contains the 5-phase algorithm for compiling source files into a topic-based wiki.

Safety rule: NEVER modify any file outside the configured output directory. Source files are read-only.

Codex Usage

In Codex, use this skill through natural-language workflow prompts instead of Claude slash commands. The preferred capture UX is intentionally simple: paste a link and say "capture this in my wiki."

Codex promptClaude command equivalent
"Initialize a wiki for this repo"/wiki-init
"Set up my global wiki"/wiki-global-init
"Capture this in my wiki: {url}. Context: {why it matters}"/wiki-capture {url} --context "{why it matters}"
"{url} — capture this in my wiki"/wiki-capture {url}
"Compile changed sources into the wiki"/wiki-compile
"Search the compiled wiki for architecture decisions"/wiki-search architecture decisions
"Answer this from the compiled wiki: {question}"/wiki-query {question}
"Launch the wiki knowledge graph"/wiki-visualize

The command markdown files in commands/ remain the canonical workflow specs. When those files mention ${CLAUDE_PLUGIN_ROOT}, Codex should resolve the same paths relative to the installed plugin root.

For session-start context in Codex, read hooks/wiki-session-context as the shared helper. It prints the same wiki guidance that Claude receives through the SessionStart wrapper, but no Codex hook is registered until a supported hook schema is available.

Prerequisites

Before running, read .wiki-compiler.json from the project root to get:

  • mode — "knowledge" (default, markdown files) or "codebase" (code repository)
  • sources[] — directories to scan (with optional exclude patterns)
  • output — where to write wiki articles
  • name — project/domain name for the wiki
  • topic_hints[] — optional seed topics from the user
  • link_style — "obsidian" (default) or "markdown"

Global wiki default: "my wiki" means the global wiki at ~/Knowledge unless LLM_WIKI_GLOBAL_DIR is set. Local/project wikis still live wherever a repo or folder has its own .wiki-compiler.json. A user can paste a URL and say "capture this in my wiki" to save one link plus context into the global wiki by default; "capture this in this project wiki" targets the local wiki.

Note: Sources don't have to live alongside the project. Captures are stored under wiki-sources/captures/ in the target wiki. /fetch-bookmarks <source> can pull batches from external services (X bookmarks today; Readwise, Pocket, GitHub stars planned) into a local directory that appears in sources[] alongside everything else.

Codebase mode additional config:

  • service_discovery — "auto" (detect monorepo vs single project) or "manual"
  • knowledge_files[] — glob patterns for priority documentation files (README.md, CLAUDE.md, etc.)
  • deep_scan — false (default) or true (also read key source files for richer articles)
  • code_extensions[] — file extensions to consider as source code (e.g., .ts, .py, .go)

Phase 1: Scan Sources

Knowledge mode (default)

  1. For each entry in sources[], list all .md files using Glob
  2. Exclude any paths matching exclude patterns (e.g., the wiki/ output directory itself)
  3. Read .compile-state.json from the output directory
  4. Compare file list against previous state to identify new or changed files
  5. On first run (no prior state), treat ALL files as new

Codebase mode

  1. For each entry in sources[], scan for knowledge files matching knowledge_files[] patterns:
    • Documentation: README.md, CLAUDE.md, AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md
    • API contracts: *.proto, *.graphql, openapi.yaml, openapi.json
    • Decision records: ADR-*.md, docs/adr/*.md
    • Infrastructure: docker-compose.yml, Dockerfile, k8s/*.yaml
    • Operations: docs/runbooks/*.md, CHANGELOG.md, .env.example
  2. If deep_scan is true, also scan for key source files per topic area:
    • Entry points: index.ts, main.py, main.go, lib.rs, App.swift, etc.
    • Type definitions: types.ts, models.py, schema.prisma, *.proto
    • Config files: package.json, tsconfig.json, pyproject.toml, go.mod, Cargo.toml
    • Limit to ~20 source files per topic area to control token cost
  3. Exclude: node_modules/, dist/, .git/, vendor/, __pycache__/, .build/, target/, and configured exclude patterns
  4. Read .compile-state.json and compare to identify new or changed files
  5. On first run, treat ALL discovered files as new

Phase 2: Classify and Discover Topics

Knowledge mode (default)

  1. For each source file, read its:
    • File path (directory structure is a strong signal)
    • Title (first # heading)
    • First 500 characters of content
    • Source date — extract using this precedence: frontmatter posted_at / date / last_updated > filename date pattern (e.g., 2026-04-15-standup.md) > file mtime. Parse to YYYY-MM-DD. Track alongside the file path — every source should have a date, or be explicitly marked undated.
  2. Classify each file into one or more topics based on content signals
  3. Use topic_hints from config as seed topics when available
  4. Prefer existing topic slugs from .compile-state.json — avoid creating near-duplicates
  5. A single file CAN belong to multiple topics
  6. Files that don't match any topic: group them — if 3+ unclassified files share a theme, create a new topic
  7. Topic slugs should be lowercase-kebab-case (e.g., d1-retention, push-notifications)
  8. Classify each topic as time-sensitive or stable (used by Phase 3 for date annotations):
    • Time-sensitive (default when unsure): any topic touching fast-moving domains — AI tooling/architecture, UI/design patterns, growth/marketing tactics, workflows, dev tools, inspiration-*, or any topic drawing ≥50% of its sources from external bookmark directories.
    • Stable: career/visa/personal-growth/sessions-*/relationship topics where claims don't decay on short timescales.
    • Err toward time-sensitive — the cost of annotating a date on stable content is low; the cost of confident-sounding stale claims is high.

Topic detection guidance:

  • Use directory names as strong signals (files in retention/ likely belong to a retention topic)
  • Use headings and key terms in content as secondary signals
  • Meeting notes and session histories often belong to multiple topics
  • Team memory files (gotchas, decisions, dead-ends) contain entries for many topics — classify by scanning content

Codebase mode

Topic discovery uses a 3-pass approach: structure → knowledge → optional deep scan.

Pass 1 — Structure scan (automatic topic discovery):

  1. Detect project type by looking for manifest files in the root:

    • package.json → Node.js/JavaScript/TypeScript
    • go.mod → Go
    • Cargo.toml → Rust
    • pyproject.toml / requirements.txt / setup.py → Python
    • Gemfile → Ruby
    • *.sln / *.csproj → .NET
    • Package.swift → Swift
    • pom.xml / build.gradle → Java/Kotlin
  2. Detect monorepo vs single project:

    • Monorepo/microservices: Multiple directories each containing their own manifest file (e.g., services/auth/package.json, services/billing/package.json). Each service directory = a topic.
    • Single project: One manifest at root. Use top-level directory structure as topic boundaries (e.g., src/auth/, src/api/, src/models/ each become topics).
  3. Auto-create cross-cutting topics when relevant files exist:

    • infrastructure — if docker-compose.yml, Dockerfile, k8s/, .github/workflows/ exist
    • testing — if tests/, __tests__/, spec/, test/ directories exist
    • deployment — if CI/CD configs, Dockerfile, deployment scripts exist

Pass 2 — Knowledge file scan (primary sources):

For each topic area discovered in Pass 1:

  1. Find all knowledge files (from knowledge_files[] config) within that topic's directory
  2. Read each knowledge file's content — these are the primary sources for compilation
  3. A knowledge file CAN belong to multiple topics (e.g., root README.md touches all topics)
  4. Root-level knowledge files (./README.md, ./CLAUDE.md, ./ARCHITECTURE.md) contribute to ALL topics or get their own project-overview topic

Pass 3 — Deep scan (optional, when deep_scan: true):

For each topic area, also read key source files to enrich understanding:

  1. Entry points: index.ts, main.py, main.go, lib.rs, App.swift, app.py
  2. Type definitions: types.ts, models.py, schema.prisma, *.proto, types.go
  3. Route/API definitions: routes.ts, api.py, handlers.go, controller.ts
  4. Config: package.json (dependencies), tsconfig.json, language-specific config
  5. Limit to ~20 files per topic to control token cost
  6. These supplement knowledge files — they add implementation detail to the article's Architecture, API Surface, and Data sections

Classification output is identical to knowledge mode: topic slug → list of source files. The rest of the pipeline (Phases 3-5) runs unchanged.

Topic slug conventions for codebases:

  • Service names: auth-service, billing-service, notification-service
  • Module names: auth, api-routes, data-layer, ui-components
  • Cross-cutting: infrastructure, testing, deployment, shared-utils

Article template: When mode is codebase, use ${CLAUDE_PLUGIN_ROOT}/templates/codebase-article-template.md as the fallback template (instead of the default knowledge template). If article_sections is set in config, use those sections (same as knowledge mode).

Phase 3: Compile Topic Articles

For EACH topic that has new or changed source files:

  1. Read ALL source files classified under that topic (need full context, not just changed files)

  2. Write the topic article to {output}/topics/{topic-slug}.md

  3. Determine article structure:

    • If .wiki-compiler.json has an article_sections array: use those sections in order. Each section's description field tells you what content belongs there.
    • If article_sections is absent (legacy configs without this field): fall back to the default template at ${CLAUDE_PLUGIN_ROOT}/templates/article-template.md
  4. Fill every section with specific, factual content -- no placeholders

  5. Summary should be a standalone briefing: someone reading just this section should understand the current state

  6. Sources must list every source file that contributed, using the configured link style

  7. Coverage indicators -- each section heading must include a coverage tag:

    • [coverage: high -- N sources] -- 5+ sources contributed to this section, detailed synthesis. Reader can trust this section without checking raw files.
    • [coverage: medium -- N sources] -- 2-4 sources, decent but may miss detail. Reader should check raw sources for granular or recent questions.
    • [coverage: low -- N sources] -- 0-1 sources or sparse data. Reader should read the raw sources directly.

    Calculate coverage per section, not per article. An article might have high coverage on Summary but low coverage on Experiments. This tells the reader (human or AI agent) exactly when to trust the wiki vs when to fall back to raw files.

  8. Time-decay annotations — apply these rules so readers can calibrate claims against when they were captured. Use the source_date collected in Phase 2.

    Define the staleness threshold:

    • Time-sensitive topics: claims older than 6 months are "aging", older than 18 months are "stale"
    • Stable topics: claims older than 24 months are "aging", older than 48 months are "stale"

    Apply these conventions:

    • Summary section for time-sensitive topics: lead with the date range of sources, e.g., "Sources span 2024-01 to 2026-04. Recent consensus (<12mo): … Older patterns (>18mo, may be stale): …". Do not blend old and new claims as if equivalent.
    • Timeline / Key Decisions: order bullets reverse-chronologically (newest first). Prefix each bullet with its date. Prefix stale bullets with ⚠️ [YYYY-MM, may be stale] so the reader can skim past them.
    • Per-section [as of YYYY-MM] tag: when a section rests primarily on aging sources (older than the topic's aging threshold), add [as of YYYY-MM] next to the coverage tag, where YYYY-MM is the median source date.
    • Conflicting sources: when two sources disagree and one is materially newer (>12 months for time-sensitive, >24 months for stable), prefer the newer synthesis and note the shift explicitly in Key Decisions: "YYYY-MM: {earlier framing} → {new framing}". Attribute both to their source files.
    • Bookmark-dominated topics (≥50% of sources from external bookmark directories like ~/.ft-bookmarks/md/bookmarks/): always annotate bullets with inline dates, and mention the dominant date range in Summary. Tweets are snapshots of a moment — never present them as timeless.

    Do NOT delete stale content. Flag, re-order, or annotate. The wiki is a time-series artifact; old entries have historical value even when no longer current.

Link style:

  • obsidian: Use [[relative/path/to/file]] (without .md extension)
  • markdown: Use [filename](relative/path/to/file.md)

Relative paths should be from the topics/ directory to the source file.

Parallel compilation: When possible, compile multiple topic articles in parallel using subagents. Each subagent gets one topic + its source files. This significantly speeds up first-run compilation.

IMPORTANT — Sequencing: Parallel dispatch is ONLY for Phase 3 (topic article compilation). After ALL parallel agents have returned and all topic articles are written, the PARENT process MUST continue to Phase 3.5 (concept discovery). Do NOT end the compilation after Phase 3. The remaining phases (3.5, 3.7, 4, 5) run sequentially in the parent process after parallel compilation completes.

Phase 3.5: Discover and Compile Concept Articles

This phase MUST run after Phase 3 completes. Read the topic articles that were just compiled and look for cross-cutting patterns. These become concept articles -- stored in {output}/concepts/.

How to discover concepts:

  1. Read all topic articles that were just compiled (or all if first run)
  2. Look for patterns that appear in 3+ topic articles:
    • Recurring decisions -- the same tradeoff appearing in different contexts (e.g., "speed vs quality" showing up in retention decisions, push notification strategy, and experiment design)
    • Relationship patterns -- a person, team, or stakeholder who appears across multiple topics with consistent dynamics
    • Methodology evolution -- how an approach changed over time across topics (e.g., "how we measure retention" evolving from n-day to bracket)
    • Recurring failures -- the same type of mistake across different domains (e.g., "trusting aggregated data without checking raw events")
  3. Check schema.md for existing concepts -- prefer updating existing concept articles over creating new ones
  4. Only create a concept if it genuinely connects 3+ topics with a non-obvious insight. Don't force concepts.

Concept article format:

Write to {output}/concepts/{concept-slug}.md:

---
concept: {Concept Name}
last_compiled: {YYYY-MM-DD}
topics_connected: [{topic1}, {topic2}, {topic3}]
status: active
---

# {Concept Name}

## Pattern
{1-2 paragraphs describing the cross-cutting pattern. What keeps recurring and why.}

## Instances
{Each time this pattern appeared, with dates and context}
- **{date}** in [[../topics/{topic}]]: {what happened}
- **{date}** in [[../topics/{topic}]]: {what happened}

## What This Means
{Synthesis -- what the pattern tells you about your work, decisions, or blind spots.
This is the "so what" that Farzapedia calls the writer's job.}

## Sources
- [[../topics/{topic1}]]
- [[../topics/{topic2}]]

Important: Concept articles are interpretive, not just factual. They answer "what does this pattern mean?" not just "what happened?" This is what makes them useful for strategic and creative thinking.

Create the concepts/ directory if it doesn't exist.

Phase 3.7: Generate or Update Schema

If {output}/schema.md does not exist (first run):

  1. Generate it from ${CLAUDE_PLUGIN_ROOT}/templates/schema-template.md
  2. Fill in the Topics section AND Concepts section with all discovered slugs and descriptions
  3. Add an Evolution Log entry: "{today's date}: Initial schema generated from {N} topics, {N} concepts"

If {output}/schema.md already exists:

  1. Read it BEFORE Phase 2 (classification) -- use its topic list, concept list, and naming conventions
  2. After Phase 3.5 (concepts), check for new topics and concepts not in the schema
  3. Add any new topics/concepts to the schema
  4. Add an Evolution Log entry if anything was added: "{today's date}: Added {slug} -- {reason}"
  5. Never remove topics or concepts from schema without human approval -- flag them as candidates instead

The schema is the source of truth for wiki structure. The human can edit it between compiles to rename topics, merge them, or change conventions. The compiler respects those changes.

Phase 4: Update INDEX.md

Write to {output}/INDEX.md:

# {name} Knowledge Base

Last compiled: {today's date}
Total topics: {count} | Total sources: {unique file count}

## Topics

| Topic | Also Known As | Sources | Last Updated | Status |
|-------|--------------|---------|-------------|--------|
| [[topics/{slug}]] | {keyword aliases} | {count} | {date} | active |

## Concepts

| Concept | Connects | Last Updated |
|---------|----------|-------------|
| [[concepts/{slug}]] | {topic1}, {topic2}, {topic3} | {date} |

## Recent Changes
- {date}: {what changed in this compilation run}

Keyword aliases: For each topic, include alternate names, abbreviations, and related terms that someone might search for. For example, a topic called side-quest-ideas might have aliases "FitOS, Growth OS, Paperclip, ClawShip". These help /wiki-search and Claude find the right topic even when the user uses different terminology.

Concepts section: List all concept articles with the topics they connect. If no concepts exist yet, omit this section.

Always regenerate INDEX.md, even if no topics changed (it's cheap).

Phase 5: Update State and Log

  1. Log — Append to {output}/log.md:
## {today's date}

**Topics updated:** {list}
**New topics:** {list or "none"}
**Sources scanned:** {count}
**Sources changed:** {count}
  1. Compile state — Update {output}/.compile-state.json:
{
  "last_compiled": "{today's date}",
  "topics": ["{slug1}", "{slug2}", ...],
  "source_locations": ["{path1}", "{path2}", ...],
  "total_sources_scanned": {count}
}

Phase 6: Generate CONTEXT.md (codebase mode only, first run)

On the first compile (no prior .compile-state.json), generate {output}/CONTEXT.md:

# Codebase Wiki — Navigation Guide

This project has a compiled knowledge wiki. Use it instead of scanning raw files.

## How to use this wiki

1. Start at INDEX.md — scan the topic table to find relevant modules
2. Read 1-3 topic articles relevant to your current task
3. Check coverage tags:
   - [coverage: high] — trust this section, skip raw files
   - [coverage: medium] — good overview, check raw sources for implementation details
   - [coverage: low] — read the raw source files listed in Sources
4. Check concepts/ for cross-cutting patterns (auth strategy, error handling, etc.)
5. Only read raw source files when you need code-level detail

## When NOT to use the wiki
- Writing new code (read the actual source files for exact syntax/types)
- Debugging a specific function (go to the file directly)
- The wiki article says [coverage: low] for what you need

## Stats
Compiled: {date} | Topics: {N} | Sources: {M} | Auto-updates on session start

On subsequent compiles, update the Stats line in CONTEXT.md.

After generating CONTEXT.md, ask the user (don't auto-modify): "Want me to add a reference to wiki/CONTEXT.md in your CLAUDE.md? This helps the agent discover the wiki automatically."

Output

After compilation, show a summary to the user:

  • Topics created/updated (with article line counts)
  • Total sources scanned
  • Any files that couldn't be classified
  • Any suggested new topics for next run
  • Time taken

Commands 12

Fetch Bookmarks from an External Source

Pull bookmarks from an external service (X/Twitter today; Readwise, Pocket, GitHub stars planned) into a local directory that /wiki-compile can consume. Optional — only needed when you want wiki topics synthesized from external sources, not just files already on disk.

The command itself is a thin dispatcher. Each source has its own adapter file that handles dependency checks, auth, sync, and wiring.

Instructions

Step 1: Parse arguments

Accept one of these forms:

  • /fetch-bookmarks <source> — sync once (default).
  • /fetch-bookmarks schedule <source> — install a daily auto-sync job.
  • /fetch-bookmarks schedule <source> --uninstall — remove the auto-sync job.
  • /fetch-bookmarks (no args) — list available adapters and usage; then stop.

When listing adapters, glob ${CLAUDE_PLUGIN_ROOT}/skills/wiki-compiler/adapters/*.md:

Usage:
  /fetch-bookmarks <source>                          Sync once
  /fetch-bookmarks schedule <source>                 Install daily auto-sync
  /fetch-bookmarks schedule <source> --uninstall     Remove auto-sync

Available sources:
- x — X/Twitter bookmarks (via Field Theory CLI)

More adapters planned: readwise, pocket, github-stars.

Step 2: Locate the adapter

  • Resolve the adapter file at ${CLAUDE_PLUGIN_ROOT}/skills/wiki-compiler/adapters/{source}.md.
  • If the file does not exist, print:
    No adapter for "{source}" yet. Available: {list}.
    Want to contribute one? See adapters/x.md for the contract.
    
    Then stop.

Step 3a: One-off sync (default)

  • Read the adapter file in full.
  • Follow its numbered steps in order. Each adapter is self-contained and handles its own preflight, consent prompts, sync, and config updates.
  • Surface the adapter's step-by-step progress to the user as you go. Do not retry failing steps silently — if a step fails, stop and show the error.
  • After successful completion, print:
    Bookmarks fetched. Run /wiki-compile to synthesize them into topic articles.
    
    Do not auto-invoke /wiki-compile.

Step 3b: Install auto-sync (schedule <source>)

  • Read the adapter file and look for its ## Scheduling section. It must document:
    • sync_command — the shell command to run on a schedule (e.g., ft sync && ft md for x)
    • default_cadence — recommended schedule (e.g., "daily 03:00 local")
    • log_path — where the sync command writes stdout/stderr
  • If the adapter has no ## Scheduling section, tell the user this adapter doesn't support auto-sync yet and stop.
  • macOS: Generate a launchd plist at ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist using the adapter's sync_command and default_cadence. Label: dev.llm-wiki-compiler.{source}-sync. Include StandardOutPath and StandardErrorPath pointing at log_path. Use /bin/bash -lc "<sync_command>" so the login shell loads PATH. Set RunAtLoad to false.
  • Run launchctl unload ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist 2>/dev/null first (idempotent), then launchctl load ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist.
  • Verify with launchctl list | grep dev.llm-wiki-compiler.{source}-sync.
  • Print: next scheduled run time, log path, and the uninstall command. Example:
    ✓ Auto-sync installed. Next run: tomorrow 03:00 local.
    Log: ~/.ft-bookmarks/autosync.log
    Uninstall: /fetch-bookmarks schedule x --uninstall
    
  • Linux / WSL: Don't auto-install. Print a crontab snippet the user can paste:
    # Add this with `crontab -e`:
    0 3 * * * /bin/bash -lc '<sync_command> >> <log_path> 2>&1'
    
  • Windows: Print a Task Scheduler hint; don't auto-install.

Step 3c: Uninstall auto-sync (schedule <source> --uninstall)

  • macOS: Run launchctl unload ~/Library/LaunchAgents/dev.llm-wiki-compiler.{source}-sync.plist 2>/dev/null, then delete the plist file.
  • Print confirmation.
  • If the plist doesn't exist, say so and stop without error.

Arguments

  • <source> — slug matching an adapter file (currently: x).
  • schedule <source> — install auto-sync for this source.
  • schedule <source> --uninstall — remove auto-sync for this source.
  • No arguments: prints help listing available adapters.

Adapter contract (for contributors)

Each adapter is a self-contained markdown file that the dispatcher follows. Adapters must:

  1. Preflight runtime and CLI dependencies. Abort with a friendly install link if a prerequisite is missing — never auto-install a runtime.
  2. Get explicit user consent before installing any tool (npm install, pip install, etc.). Show the project URL and license.
  3. Run the third-party sync command and surface its output verbatim so the user can respond to any prompts it raises.
  4. Ensure the source's output ends up as markdown at a stable path.
  5. Read .wiki-compiler.json from the project root. If that path is not already present in sources[], ask the user to confirm adding it, then write the update preserving all other fields.
  6. Print a "run /wiki-compile" suggestion. Never auto-invoke compile.
  7. Optional: ## Scheduling section documenting sync_command, default_cadence, and log_path so /fetch-bookmarks schedule <source> can wire launchd/cron. Adapters without this section don't support auto-sync.

See plugin/skills/wiki-compiler/adapters/x.md for the reference implementation.

Capture a Link Into the Wiki

Capture a URL plus user context, normalize it into a durable markdown source, then connect it to the global wiki, local project wiki, or both.

Arguments

  • /wiki-capture <url> — capture a link and ask for context
  • /wiki-capture <url> --context "why this matters" — capture with explicit context
  • /wiki-capture <url> --no-update — only write the source markdown; do not update wiki articles

Codex prompt equivalents:

https://example.com/article

capture this in my wiki

or:

Capture this in my wiki:
{url}

Context: {why it matters to the work I am doing}

Instructions

Step 1: Resolve target wiki

Default global wiki:

~/Knowledge

Override:

LLM_WIKI_GLOBAL_DIR=/path/to/wiki-root

Routing rules:

  • If the user says "my wiki", "global wiki", "personal wiki", or just "capture this in my wiki", use the global wiki by default.
  • If the user says "this repo", "this project", "local wiki", or "project wiki", use the nearest local .wiki-compiler.json.
  • If the user says "both", capture into both global and local wiki targets.
  • If no local .wiki-compiler.json exists and the user asks for local capture, offer to initialize one.
  • If no global .wiki-compiler.json exists, initialize the global wiki automatically from templates/global-wiki-config.json before capture.
  • If a local wiki exists and the capture defaults to global, mention that a local wiki is available and offer to also connect the source there when it clearly relates to the current project.

Step 2: Validate wiki config

  • For each target wiki, read .wiki-compiler.json.
  • Confirm output is set.
  • If the target wiki has not been compiled yet, still allow capture, but explain that connections will be stronger after the first compile.

Step 3: Collect user context

  • If --context is absent, ask:

    "What should I pay attention to? For example: how this link relates to the product, codebase, strategy, customer, or workflow."

  • Treat this context as part of the source, not as a transient instruction.
  • Do not summarize the link generically. Read it through the user's context.

Step 4: Route to a capture adapter

Choose exactly one adapter:

URL patternAdapter
youtube.com, youtu.beskills/wiki-compiler/adapters/capture-youtube.md
x.com, twitter.comskills/wiki-compiler/adapters/capture-x.md
Any other http or https URLskills/wiki-compiler/adapters/capture-web.md

Read the adapter and follow it. The adapter must return a normalized markdown file path under the configured capture source directory.

Step 5: Ensure capture source is configured

  • Default capture source directory: wiki-sources/captures/
  • If .wiki-compiler.json already includes that path in sources[], leave it alone.
  • Otherwise ask:
    Add wiki-sources/captures/ to this wiki's sources so future compiles include captured links? (y/n)
    
  • On yes, append:
    {
      "path": "wiki-sources/captures/",
      "description": "Captured links with user context"
    }
    
  • Preserve every other config field. Do not reformat unrelated config.

Step 6: Connect it to the wiki

If --no-update is set:

  • Stop after writing the source file and wiring the source directory.
  • Print the source path and suggest running /wiki-ingest {source_path} or /wiki-compile.

Otherwise:

  1. Read {output}/INDEX.md and {output}/schema.md if they exist.
  2. Read the normalized source file.
  3. Identify 1-3 likely existing topics or concepts this source connects to.
  4. Present a short connection plan:
    Captured: {title}
    
    Likely connections:
    - {topic}: {why it fits}
    - {concept}: {why it fits}
    
    Proposed update:
    - Update existing topic(s): {list}
    - Create new topic/concept only if needed: {slug or "none"}
    
  5. Ask for confirmation before writing wiki article changes.
  6. On confirmation, follow the /wiki-ingest flow using the captured markdown file as the source. Integrate the user's context and extracted insights into topic/concept articles, with provenance back to the captured source and original URL.

Step 7: Output summary

Print:

Captured: {title}
Source: {path}
Original URL: {url}

Connected to:
- {topic/concept}: {what changed}

Target wiki:
- {global|local|both}: {wiki root}

Next:
- Run /wiki-lint to check cross-links and coverage
- Run /wiki-visualize to see the new graph connections

Source format

Use templates/captured-source-template.md as the source shape. Every captured source must include:

  • source_type
  • url
  • captured_at
  • title
  • user_context
  • extracted content or transcript
  • relevance notes
  • candidate wiki connections

Safety

  • Never overwrite an existing captured source. If the slug exists, append -2, -3, etc.
  • Never update raw source files outside wiki-sources/captures/.
  • Never auto-install tools without explicit user consent.
  • Do not auto-create a new topic when an existing topic is a reasonable fit.

Compile Knowledge Base Wiki

Compile all configured markdown source files into a topic-based wiki.

Instructions

  1. Read configuration from .wiki-compiler.json in the project root (or nearest parent directory). If not found, tell the user to run /wiki-init first.

  2. Validate configuration:

    • sources[] must have at least one entry
    • output must be set
    • Source paths must exist
  3. Read schema from {output}/schema.md if it exists. Use it to guide topic/concept classification and naming. If it doesn't exist (first run), it will be generated in Phase 3.7.

  4. Invoke the wiki-compiler skill to run the compilation:

    • Pass article_sections from config to the skill (if present — legacy configs may not have this field)
    • Phase 1: Scan sources
    • Phase 2: Classify and discover topics (respecting schema if present)
    • Phase 3: Compile topic articles using article_sections for structure (use parallel agents when possible)
    • Phase 3.5: Discover and compile concept articles (cross-cutting patterns)
    • Phase 3.7: Generate or update schema.md
    • Phase 4: Update INDEX.md (now includes concepts section)
    • Phase 5: Update state and log
  5. Show completion summary with topics created/updated, concepts discovered, source count, and schema changes.

Arguments

  • No arguments: incremental compilation (recompile changed topics)
  • --full: force recompile all topics regardless of changes
  • --topic {slug}: recompile only the specified topic
  • --dry-run: show what would be compiled without writing files

Initialize the Global Wiki

Create or repair the user's default cross-project wiki.

Arguments

  • /wiki-global-init — initialize the default global wiki
  • /wiki-global-init --path ~/Somewhere — initialize a custom global wiki directory

Codex prompt equivalents:

Set up my global wiki

or:

Use ~/Knowledge as my global wiki

Global wiki location

Default:

~/Knowledge

Override:

LLM_WIKI_GLOBAL_DIR=/path/to/wiki-root

Prefer ~/Knowledge over hidden app storage because users can browse it, back it up, sync it, edit sources, and understand where their knowledge lives.

Instructions

  1. Resolve the target directory:
    • --path wins if provided.
    • Else LLM_WIKI_GLOBAL_DIR if set.
    • Else ~/Knowledge.
  2. Create the directory if it does not exist.
  3. Create these subdirectories if missing:
    wiki-sources/captures/
    wiki/
    
  4. If .wiki-compiler.json does not exist, create it from templates/global-wiki-config.json.
  5. If .wiki-compiler.json exists, verify it includes wiki-sources/captures/ in sources[]; ask before adding it if missing.
  6. Do not overwrite an existing config.
  7. Print:
    Global wiki ready at {path}
    
    Try:
    https://example.com
    capture this in my wiki
    

Default config

Use templates/global-wiki-config.json as the default config shape. The default wiki is a knowledge-mode wiki with capture sources enabled and output at wiki/.

Ingest a Single Source

Interactive workflow for adding one source file to the wiki. The LLM reads the file, discusses key takeaways with the user, then updates relevant topic articles.

Instructions

Step 1: Validate

  • Read .wiki-compiler.json from the project root (or nearest parent directory). If not found, tell the user to run /wiki-init first.
  • Accept one argument: the file path to ingest (e.g., /wiki-ingest Knowledge/meetings/2026-04-07-standup.md)
  • If no argument provided, ask: "Which file would you like to ingest?"
  • Verify the file exists and is a .md file
  • Check that the file is within one of the configured sources[] directories (warn if not, but allow it)

Step 2: Read and discuss

  • Read the full source file
  • Present a brief summary of key takeaways (3-5 bullet points)
  • Ask the user: "Anything you want me to emphasize or de-emphasize when updating the wiki?"
  • Wait for the user's response before proceeding — this is the interactive part where the user guides what matters

Step 3: Classify

  • Read {output}/schema.md to understand existing topics and naming conventions
  • Determine which existing topics this source belongs to (can be multiple)
  • If the source introduces a genuinely new topic not in the schema, propose creating it
  • Show the user: "This file touches these topics: [list]. I'll update each one. Sound right?"
  • Wait for confirmation before proceeding

Step 4: Update topic articles

For each affected topic:

  1. Read the current topic article from {output}/topics/{slug}.md
  2. Read article_sections from .wiki-compiler.json (or use default template from ${CLAUDE_PLUGIN_ROOT}/templates/article-template.md if absent)
  3. Integrate the new source's information into the relevant sections
  4. Respect the user's emphasis guidance from Step 2
  5. Update coverage indicators — the source count may change the coverage level for some sections
  6. Add the new source to the Sources section (using configured link_style)
  7. Update the source_count in the article frontmatter
  8. Write the updated article

If a new topic was proposed and approved in Step 3:

  • Create a new topic article using the configured article_sections
  • Populate it with content from this source

Step 5: Update schema, index, and state

  1. Schema — If a new topic was created, add it to {output}/schema.md with an evolution log entry: "{date}: Added {slug} — discovered during ingest of {filename}"
  2. INDEX.md — Regenerate with updated source counts and dates
  3. Log — Append to {output}/compile-log.md:
    ## {date} — ingest
    **Source:** {filename}
    **Topics updated:** {list}
    **New topics:** {list or "none"}
    
  4. State — Update .compile-state.json with new source in the file list

Step 6: Summary

Show what changed:

Ingested: {filename}

Topics updated:
- {topic1}: {brief description of what was added/changed}
- {topic2}: {brief description of what was added/changed}

New topics created: {list or "none"}

Tip: Run /wiki-lint to check for new cross-references or contradictions.

Arguments

  • Single argument: file path to ingest
  • No arguments: prompts user to specify a file
  • --quiet: Skip the interactive discussion (Steps 2-3 user prompts) and auto-classify. Useful for batch scripting.

Initialize Knowledge Base Wiki

Interactive, conversational setup for a new knowledge base wiki. One question at a time, multiple choice when possible.

Arguments:

  • (none) — auto-detects whether this is a codebase or knowledge project (see Auto-Detection below)
  • --codebase — force codebase mode (skip auto-detection)
  • --knowledge — force knowledge mode (skip auto-detection)

Instructions

Important: Ask ONE question per message. Wait for the user's response before moving to the next question. Never batch multiple questions. Keep the tone conversational — like a knowledgeable colleague setting things up for you.


Auto-Detection (when no flag is provided)

Before asking any questions, scan the project root to determine the mode:

  1. Check for code manifest files: package.json, go.mod, Cargo.toml, pyproject.toml, requirements.txt, Gemfile, *.sln, Package.swift, pom.xml, build.gradle
  2. Check for markdown-heavy directories: Knowledge/, docs/, notes/, content/, meetings/, research/, or any directory with 10+ .md files

Decision logic:

  • Manifest found, no markdown directories → codebase mode
  • Markdown directories found, no manifest → knowledge mode
  • Both found → ask the user:
    I see both code files and markdown knowledge directories here.
    
    A) Codebase wiki — compile a wiki about this codebase's architecture, decisions, and patterns
    B) Knowledge wiki — compile a wiki from your markdown files (meetings, notes, research)
    
  • Neither found → ask the user what they want to compile

Then proceed to the appropriate mode below.


Codebase Mode (--codebase or auto-detected)

When codebase mode is selected, use this streamlined flow instead of the standard 10-step process.

Codebase Step 1: Check for existing config

Same as standard Step 1 — check for .wiki-compiler.json and ask to reconfigure or abort.

Codebase Step 2: Auto-detect everything

Scan the project root and build a complete picture in one pass:

  1. Detect project type by looking for manifest files:

    • package.json → Node.js/TypeScript
    • go.mod → Go
    • Cargo.toml → Rust
    • pyproject.toml / requirements.txt → Python
    • Gemfile → Ruby
    • *.sln → .NET
    • Package.swift → Swift
    • pom.xml / build.gradle → Java/Kotlin
    • Multiple manifests in subdirectories → Monorepo
  2. Discover topic candidates:

    • Monorepo: each directory with its own manifest = a topic
    • Single project: major subdirectories under src/, lib/, app/, or root = topics
    • Cross-cutting topics: infrastructure (if Docker/CI exists), testing (if test dirs exist), deployment (if k8s/deploy scripts exist)
  3. Count knowledge files matching default patterns:

    • README.md, CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md
    • *.proto, *.graphql, openapi.*
    • ADR-*.md, docs/adr/*.md
    • docker-compose.yml, Dockerfile
    • CHANGELOG.md, .env.example
  4. Auto-detect project name from package.json name field, go.mod module name, directory name, or git remote.

Codebase Step 3: One confirmation prompt

Present everything in a single confirmation:

📚 I see a {project_type} project with {N} modules and {M} knowledge files.

  Topics: {topic1}, {topic2}, {topic3}, ...
  Sections: Purpose, Architecture, Talks To, API Surface, Data, Key Decisions, Gotchas
  Output: wiki/

A) Looks good — create config and compile now (recommended)
B) Customize — let me adjust topics, sections, or settings
C) Not now

If A: create config (Codebase Step 4) and immediately run /wiki-compile. If B: fall through to the standard interactive flow (Step 2 onwards) but with codebase defaults pre-filled. If C: exit.

Codebase Step 4: Create configuration

Write .wiki-compiler.json:

{
  "version": 2,
  "mode": "codebase",
  "name": "{auto_detected_name}",
  "sources": [
    { "path": "./", "exclude": ["node_modules/", "dist/", ".git/", "wiki/", "vendor/", "__pycache__/", ".build/", "target/", ".next/", "coverage/"] }
  ],
  "output": "wiki/",
  "service_discovery": "auto",
  "knowledge_files": [
    "README.md", "CLAUDE.md", "AGENTS.md", "ARCHITECTURE.md", "CONTRIBUTING.md",
    "*.proto", "*.graphql", "openapi.yaml", "openapi.json",
    "ADR-*.md", "docs/adr/*.md",
    "docker-compose.yml", "Dockerfile",
    ".env.example", "CHANGELOG.md"
  ],
  "deep_scan": false,
  "auto_update": "prompt",
  "article_sections": [
    { "name": "Purpose", "description": "What this module/service does and who depends on it", "required": true },
    { "name": "Architecture", "description": "Key files, structure, entry points" },
    { "name": "Talks To", "description": "Dependencies, communication patterns, inter-service calls" },
    { "name": "API Surface", "description": "Endpoints, exported functions, or interfaces exposed" },
    { "name": "Data", "description": "Tables, collections, queues, caches, state owned" },
    { "name": "Key Decisions", "description": "Why it was built this way, from ADRs and READMEs" },
    { "name": "Gotchas", "description": "Known issues, edge cases, failure modes" },
    { "name": "Sources", "description": "Backlinks to all contributing files", "required": true }
  ],
  "link_style": "markdown"
}

Codebase Step 5: Create output directory and compile

  1. Create wiki/, wiki/topics/, wiki/concepts/ directories
  2. Create empty wiki/.compile-state.json
  3. Create empty wiki/log.md
  4. Run the wiki-compiler skill (all 6 phases including CONTEXT.md generation)
  5. Show the first-compile summary with topic tree

Codebase Step 6: Done

📚 Wiki compiled — {N} topics from {M} files

  Topics created:
  ├── {topic1} ({count} sources) — {one-line description}
  ├── {topic2} ({count} sources) — {one-line description}
  └── {topic3} ({count} sources) — {one-line description}

  Concepts discovered:
  └── {concept1} — {description}

  Browse: wiki/INDEX.md
  Navigation guide: wiki/CONTEXT.md

Want me to add a reference to wiki/CONTEXT.md in your CLAUDE.md?

Knowledge Mode (--knowledge or auto-detected)

Step 1: Check for existing config

Look for .wiki-compiler.json in the current project root. If it exists:

You already have a wiki configured for "{name}" ({topic_count} topics, last compiled {date}).

A) Reconfigure from scratch
B) Keep current setup (abort)

If B, exit. If A, continue.

Step 2: Welcome + auto-detect

Scan the project for markdown-heavy directories. Look for:

  • Directories named Knowledge/, docs/, notes/, content/, meetings/, research/
  • Any directory containing 10+ .md files
  • Exclude: node_modules/, .git/, wiki/, build/, dist/

Present findings conversationally:

Welcome to LLM Wiki Compiler. I'll get you set up in about 5 questions.

I found {count} markdown files across your project:

  {dir1}/  — {count} files
  {dir2}/  — {count} files
  {dir3}/  — {count} files

Which directories should I compile into your wiki?

A) All of the above (recommended)
B) Let me pick — show me the list
C) I'll type the paths myself

Wait for response. If B, show checkboxes. If C, ask for paths.

Step 3: Name

Got it, {count} directories selected. What should I call this knowledge base?

A) "{auto_detected_name}" (based on your project name)
B) Let me type a name

Wait for response.

Step 4: Output location

Where should the compiled wiki live?

A) {first_source}/wiki/ (recommended — keeps it near your sources)
B) docs/wiki/
C) Let me pick a different path

Wait for response.

Step 5: Sample files and propose article structure

Now read 10-15 representative .md files from the confirmed source directories:

  • Pick files from different subdirectories for breadth
  • Read the first ~500 characters + the title (first # heading) of each
  • Note what kinds of content you're seeing

Based on what you found, generate 5-8 article sections that fit the domain. Then present:

I sampled {N} of your files. Looks like you have {description of content types}.

Here's the article structure I'd suggest for your wiki:

  1. Summary — standalone briefing of the topic
  2. {section} — {description}
  3. {section} — {description}
  4. {section} — {description}
  5. {section} — {description}
  6. Sources — backlinks to all contributing files

A) Looks good, use this (recommended)
B) I want to add or remove sections
C) Regenerate — try a different structure

If B, ask which sections to add/remove/rename. If C, regenerate with different emphasis.

Rules for section generation:

  • Always include Summary first and Sources last — these are universal
  • Middle sections are domain-specific — match the actual content patterns observed
  • Examples of what the LLM might propose by domain:
    • Product/growth: Timeline, Current State, Key Decisions, Experiments & Results, Gotchas, Open Questions
    • Research: Key Findings, Methodology, Evidence, Gaps & Contradictions, Open Questions
    • Personal journal: Themes & Patterns, Progress, Reflections, Action Items
    • Book notes: Characters, Themes, Plot Threads, Connections, Quotes
    • Technical docs: Architecture, API Surface, Dependencies, Known Issues, Migration Notes
    • Business/team: Stakeholders, Decisions, Action Items, Meeting History, Open Threads

Step 6: Wiki mode

Almost done. How should the wiki integrate with your workflow?

A) Staging — wiki supplements your existing setup, no changes needed (recommended for first-time)
B) Recommended — Claude reads wiki before raw files
C) Primary — wiki is the main knowledge source, raw files only for detail

You can change this anytime in .wiki-compiler.json.

Wait for response.

Step 7: Stale detection

Last question. Want me to warn you when your wiki is out of date?

If source files change after a compile, the plugin can flag it at session start:
"Wiki may be stale — 12 files changed. Run /wiki-compile to update."

A) Yes, warn me (recommended)
B) No thanks, I'll compile manually

If A, set auto_update to "prompt". If B, set to "off".

Step 8: Create configuration

Write .wiki-compiler.json to the project root:

{
  "version": 1,
  "name": "{name}",
  "sources": [
    { "path": "{path1}/", "exclude": ["wiki/"] },
    { "path": "{path2}/" }
  ],
  "output": "{output_path}/",
  "mode": "{selected_mode}",
  "auto_update": "{selected_auto_update}",
  "article_sections": [
    { "name": "Summary", "description": "{description}", "required": true },
    { "name": "{section2}", "description": "{description}" },
    { "name": "{section3}", "description": "{description}" },
    { "name": "{section4}", "description": "{description}" },
    { "name": "{section5}", "description": "{description}" },
    { "name": "Sources", "description": "backlinks to all contributing source files", "required": true }
  ],
  "topic_hints": [],
  "link_style": "obsidian"
}

Step 9: Create output directory

Create:

  • {output}/ directory
  • {output}/topics/ directory
  • {output}/.compile-state.json with initial empty state
  • {output}/compile-log.md with initial empty log

Step 10: Done

Wiki initialized for "{name}"

  Sources:    {count} directories, ~{file_count} markdown files
  Output:     {output_path}
  Structure:  {section_count} sections ({section names})
  Mode:       {mode}
  Stale warnings: {on/off}

Next steps:
  1. Run /wiki-compile to build your first compilation (5-10 min)
  2. Open {output_path}/INDEX.md in Obsidian to browse
  3. After compiling, run /wiki-migrate to switch your AGENTS.md to wiki-first

Edit .wiki-compiler.json anytime to adjust settings.

Lint Knowledge Base Wiki

Run health checks on the compiled wiki to find issues.

Instructions

  1. Read configuration from .wiki-compiler.json. If not found, tell the user to run /wiki-init first.

  2. Read the wiki state:

    • Read {output}/INDEX.md for current topics
    • Read {output}/schema.md for expected structure (if exists)
    • Read {output}/.compile-state.json for last compilation state
  3. Run these checks:

Check 1: Stale Articles

Compare source file modification dates against .compile-state.json. Flag topics whose sources have changed since last compile.

Check 2: Orphan Pages

Check each wiki article's Sources section. Flag articles where:

  • Source files no longer exist (were deleted or moved)
  • Article has 0 sources listed

Check 3: Missing Cross-References

For each pair of topics, count shared sources. If two topics share 3+ sources but neither references the other, suggest a cross-reference.

Check 4: Low Coverage Sections

Scan all articles for [coverage: low] tags. List them as improvement candidates -- these sections should either be expanded with more sources or flagged as known gaps.

Check 5: Contradictions

Compare key facts across articles. Look for:

  • Different dates for the same event in different articles
  • Conflicting metrics (e.g., "D1 is 17.5%" in one article, "D1 is 13.3%" in another)
  • Decisions described differently across topics

Check 6: Schema Drift

If schema.md exists:

  • Topics in topics/ directory not listed in schema.md
  • Topics listed in schema.md that don't have a corresponding article
  • Article sections that don't match the schema's Article Structure
  1. Output a summary:
Wiki Lint: "{name}"
──────────────────────────
Stale:          {N} topics (sources changed since last compile)
Orphans:        {N} articles with missing sources
Cross-refs:     {N} missing links suggested
Low coverage:   {N} sections across {N} topics
Contradictions: {N} found
Schema drift:   {N} mismatches

{Details for each finding, grouped by check}
  1. Suggest fixes:

    • Stale topics: "Run /wiki-compile to refresh"
    • Orphans: "Source was deleted -- recompile to remove stale references"
    • Cross-refs: "Consider adding a reference to [[topic-b]] in topic-a's Summary"
    • Contradictions: "Check {source1} vs {source2} for the correct value"
    • Schema drift: "Add {topic} to schema.md" or "Remove {topic} from schema.md"
  2. Log the lint run by appending to {output}/log.md:

### {date} — Lint
- Stale: {N}, Orphans: {N}, Cross-refs: {N}, Low: {N}, Contradictions: {N}, Drift: {N}

Migrate to Wiki-First Startup

One-time migration command. Analyzes your AGENTS.md or CLAUDE.md session startup sequence and shows which raw file reads can be replaced by wiki articles.

Instructions

Step 1: Validate

  • Read .wiki-compiler.json — if not found, tell the user to run /wiki-init first
  • Check that the wiki has been compiled at least once (INDEX.md and topic articles exist)
  • If not compiled, tell the user to run /wiki-compile first

Step 2: Find startup instructions

Look for session startup instructions in this order:

  1. AGENTS.md in the project root
  2. CLAUDE.md in the project root
  3. Any file referenced by CLAUDE.md that contains startup/context loading instructions

Identify the section that lists files to read at session start. Look for patterns like:

  • "Read these files", "Session Startup", "Before doing any work, read..."
  • Numbered lists of file paths with descriptions
  • References to context files, knowledge bases, or startup sequences

Step 3: Map raw files to wiki topics

For each file listed in the startup sequence:

  1. Read the wiki INDEX.md to get the list of topics
  2. For each raw file, check if its content is covered by a wiki topic:
    • Match by filename appearing in a topic's Sources section
    • Match by content overlap (the raw file's key terms appearing in a topic article)
  3. Check the coverage level of the relevant topic sections

Step 4: Present the coverage report

Wiki Migration Report for {project name}

Current startup: {N} file reads

✅ {filename} → covered by {topic} [coverage: high]
✅ {filename} → covered by {topic} [coverage: high]
⚠️ {filename} → partially covered by {topic} [coverage: medium]
   → Check raw source for: {what's missing}
⚠️ {filename} → partially covered by {topic} [coverage: low]
   → Read raw source directly for granular detail
❌ {filename} → not covered by any wiki topic
   → Keep this in startup, or /wiki-ingest to add it

Summary: {covered}/{total} reads can be replaced by wiki
Estimated token savings: ~{old_tokens} → ~{new_tokens} ({reduction}% reduction)

Step 5: Generate replacement startup block

Based on the report, generate a replacement startup section that:

  1. Reads wiki INDEX.md first
  2. Lists relevant topic articles by work area
  3. Keeps any ❌ items as direct file reads (operational rules, checklists)
  4. Includes coverage-based fallback instructions

Present the replacement block to the user:

Here's a suggested replacement for your startup section:

---
{generated startup block}
---

Want me to apply this? (I'll only edit the startup section — everything else stays the same.)

Step 6: Apply (with confirmation)

Only if the user confirms:

  • Replace the startup section in AGENTS.md or CLAUDE.md
  • Keep everything outside the startup section unchanged
  • Show a diff of what changed

Never auto-apply. The user must explicitly confirm before any file is modified.

Arguments

  • No arguments: analyzes and reports
  • --apply: skip the confirmation prompt and apply immediately (for scripting)
  • --dry-run: just show the report, don't offer to apply

Query Knowledge Base Wiki

Search the compiled wiki to answer a question. Faster and cheaper than reading raw source files.

Arguments

The user's question is passed as $ARGUMENTS. Example: /wiki-query what do we know about retention?

Instructions

  1. Read configuration from .wiki-compiler.json. If not found, tell user to run /wiki-init.

  2. Read INDEX.md from the configured output directory to see all available topics.

  3. Read schema.md if it exists -- check for cross-reference rules that might point to related topics.

  4. Identify relevant topics -- based on the user's question, select 1-3 topic articles most likely to contain the answer.

  5. Read the selected topic articles from {output}/topics/.

  6. Answer the question with:

    • Specific facts, dates, and decisions from the wiki articles
    • Citations in the format: (from: {topic name} > {section})
    • If the wiki doesn't have enough detail, point the user to specific raw source files from the article's Sources section
  7. Keep it concise -- the user wants an answer, not a summary of every article you read.

  8. Offer to file the answer -- if the answer synthesizes information in a useful way that isn't already in a wiki article, ask:

    "This answer connects information across topics. Want me to file it into the wiki? (y/n)"

    If yes:

    • Append the synthesis to the most relevant topic article (add a new subsection or expand an existing section)
    • Add a note: *Filed from query on {date}*
    • Log it in {output}/log.md:
      ### {date} -- Query Filed
      - Question: "{question}"
      - Filed to: {topic-slug} > {section}
      

    If the answer doesn't add new synthesis (just restated what's already in the article), skip the filing offer.

If no wiki exists

If INDEX.md doesn't exist or the wiki hasn't been compiled yet:

Wiki not compiled yet. Run /wiki-compile first, then try your query again.

Search the Wiki

Search across all wiki articles for keywords, phrases, or topics.

Instructions

Step 1: Validate

  • Read .wiki-compiler.json from the project root (or nearest parent directory). If not found, tell the user to run /wiki-init first.
  • Accept a search query as argument (e.g., /wiki-search retention experiments)
  • If no argument provided, ask: "What are you looking for?"

Step 2: Search strategy

Use a two-tier search approach:

Tier 1 — Index scan (fast, try this first):

  • Read {output}/INDEX.md
  • Check topic names and one-line summaries for keyword matches
  • This is usually sufficient for "which topic covers X?" questions

Tier 2 — Full article search (when Tier 1 isn't enough):

  • Use Grep to search across all files in {output}/topics/ and {output}/concepts/ for the search terms
  • Return matching sections with context — include the section heading (##) and surrounding lines so the user can see the match in context
  • Search both topic articles and concept articles

Step 3: Present results

Format results clearly:

Found {N} matches for "{query}":

### Topics
- **{topic-name}** [coverage: {level}] — {matching excerpt}
  → {output}/topics/{slug}.md

### Concepts
- **{concept-name}** — {matching excerpt}
  → {output}/concepts/{slug}.md

Include coverage indicators so the user knows whether to trust the wiki excerpt or read raw sources.

If no matches found:

  • Suggest related topics that might be relevant
  • Recommend /wiki-query for synthesis questions that require connecting multiple topics
  • Suggest /wiki-ingest if the user thinks the knowledge should be in the wiki but isn't

Step 4: Offer next steps

Based on results:

  • "Want me to read the full article on {topic}?"
  • "Want to ask a deeper question? Try /wiki-query {your question}"
  • If search reveals a gap: "This area has low coverage. Want to /wiki-ingest a source to improve it?"

Arguments

  • Search query as argument (can be multiple words)
  • No arguments: prompts user to specify what they're looking for

Notes

This is a keyword/grep-based search designed to work at any scale without external dependencies. For large wikis (100+ topics) that need semantic search, consider adding qmd as an MCP server for hybrid BM25/vector search with LLM re-ranking.

Upgrade Wiki Compiler Plugin

Update the plugin to the latest version from GitHub.

Instructions

  1. Find the plugin source directory by running:

    find ~/.claude/plugins -name "llm-wiki-compiler" -type d 2>/dev/null | head -1
    
  2. Pull the latest changes:

    cd {plugin_directory} && git pull origin main
    
  3. Show what changed by reading the git log:

    git log --oneline -5
    
  4. Tell the user to restart Claude Code for the changes to take effect:

    Updated to latest version. Restart Claude Code to load the new commands and hooks.

    What's new: {list the new commits since their previous version}

If git pull fails

If the plugin was installed from marketplace (not a git clone), tell the user:

Run: claude plugin update llm-wiki-compiler
Then restart Claude Code.

Visualize Wiki Knowledge Graph

Launch an interactive canvas-based knowledge graph of your compiled wiki. Topics appear as nodes, concepts as connecting edges. Click any node to read the article.

Instructions

  1. Check that .wiki-compiler.json exists in the project root

  2. Check that the wiki has been compiled (output directory has INDEX.md)

  3. If not compiled, suggest running /wiki-compile first

  4. Start the visualization server:

    node "${CLAUDE_PLUGIN_ROOT}/visualize/server.js" --wiki-dir "{output_path}"
    
  5. Open the browser:

    open "http://localhost:3848"
    
  6. Tell the user:

    📊 Wiki Knowledge Graph running at http://localhost:3848
    
    - Click nodes to read topic articles
    - Hover edges to see concept connections
    - Search to filter topics
    - The server reads your wiki files live — changes from /wiki-compile appear immediately
    
    Stop with Ctrl+C when done.
    

Arguments

  • (none) — launch visualization for current project's wiki
  • --port {number} — use a custom port (default: 3848)

Sponsors

Details

Marketplace
ussumant/llm-wiki-compiler
Source
plugin
Author
Sumant
Category
Community