/wiki-compiler

name: wiki-compiler
description: Core compilation algorithm for the LLM Wiki Compiler. Reads source files from configured directories and compiles them into topic-based wiki articles. Supports both knowledge mode (markdown files) and codebase mode (code repositories). Called by /wiki-compile command.

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 prompt | Claude 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