Create Wiki

Create Wiki

Set up a persistent, LLM-maintained knowledge base inside a project following Andrej Karpathy's LLM Wiki pattern. The wiki uses a three-layer architecture:

• Sources (wiki/sources/) — Human-curated raw documents. Immutable. Claude reads but never modifies.
• Pages (wiki/pages/) — LLM-generated markdown pages. Claude owns these entirely — creates, updates, deletes as needed.
• Schema (wiki/schema.yaml) — Configuration defining categories, conventions, and maintenance thresholds. Co-evolves with use.

The key insight: the tedious part of maintaining a knowledge base is not the reading or thinking — it's the bookkeeping. LLMs excel at updating cross-references and maintaining consistency across dozens of pages without fatigue. Humans curate sources and ask questions. Claude handles everything else.

Input

Arguments: $ARGUMENTS

Supported arguments:

• init — Full initialization: discover project context, create wiki structure, seed pages, inject CLAUDE.md rules
• status — Show wiki health (redirects to /wiki status)
• No arguments — Same as init if no wiki exists, same as status if one does

Phase 0: Self-Invocation Confirmation

This skill can be model-invoked, and initialization writes a wiki/ tree and injects maintenance rules into CLAUDE.md that change how Claude behaves for the rest of the project's life. That must never happen unasked.

If you are invoking this skill on your own initiative — because the project is accumulating domain knowledge, context keeps getting lost between sessions, or the user said "I keep forgetting how this works" — rather than the user typing /create-wiki, confirm first with AskUserQuestion:

{
  "questions": [
    {
      "question": "Set up an LLM-maintained wiki for this project?",
      "header": "Wiki",
      "multiSelect": false,
      "options": [
        {
          "label": "Yes, initialize it",
          "description": "Creates wiki/ with sources, pages, schema, and index, seeds pages from project discovery, and adds maintenance rules to CLAUDE.md"
        },
        {
          "label": "No, not now",
          "description": "Nothing is written; you can run /create-wiki yourself at any time"
        }
      ]
    }
  ]
}

• Confirmed: proceed to the entry-point check below.
• Declined or skipped: reply "Skipped — run /create-wiki whenever you want one." and exit immediately. Create nothing, modify nothing.

When the user invokes this skill directly, skip this gate entirely and proceed. Maintenance mode on an existing wiki is the wiki working as configured and needs no gate.

Entry-Point: Init vs Maintenance Mode

Before doing anything else, determine which mode to run:

IF wiki/ directory exists AND wiki/index.md exists:
    → Run MAINTENANCE MODE (see below)
ELSE:
    → Run INITIALIZATION MODE (On `init` section below)

Check for wiki existence:

test -f wiki/index.md && echo "EXISTS" || echo "NOT_FOUND"

Maintenance Mode (wiki already exists)

Used when the user invokes the skill on a project that already has a wiki — with status, or with no argument.

Maintenance mode is idempotent — running it twice produces the same result. It updates, never re-initializes.

Maintenance Step 1: Identify Changed Sources

Nothing invokes this skill on save. There is no filesystem watcher, and a paths: declaration would only be a load gate — it makes a skill findable after Claude's own Read/Edit/Write touches a matching file, and never runs anything on its own (see ADR-0012). So identify changed sources from git:

git diff --name-only HEAD~1 HEAD

Then interpret what changed:

• wiki/sources/**/* — a source file was added or modified
• CLAUDE.md — project rules changed; wiki pages covering architecture or conventions may be stale
• LAB_NOTEBOOK.md — new findings may be wiki-worthy; check for extractable durable knowledge

Maintenance Step 2: Update Relevant Wiki Pages

For each changed source:

1. Read the changed file
2. Identify which existing wiki/pages/*.md pages reference or relate to it (check frontmatter sources: fields and content body links)
3. For source files in wiki/sources/: re-ingest the source, update pages whose content depends on it
4. For CLAUDE.md changes: update pages in the architecture, decisions, or operations categories if rules changed meaningfully
5. For LAB_NOTEBOOK.md changes: read the new entries (look for headings dated after the last ## [YYYY-MM-DD] ingest entry in wiki/log.md); extract wiki-worthy findings; create or update pages

Idempotency rule: Before creating a new page, check whether a page for that topic already exists in wiki/index.md. If it does, update the existing page rather than creating a duplicate.

Maintenance Step 3: Update index.md and log.md

• Update wiki/index.md for any created or modified pages
• Append to wiki/log.md:

  ## [YYYY-MM-DD] update | Maintenance triggered by <trigger-description>
  Changed: <list of pages updated>
  Source: <what triggered the run>
  

Maintenance Step 4: Report

Print a brief summary:

Wiki maintenance complete.

  Trigger:  <what file changed>
  Updated:  <N pages updated or created>
            - Page Title (category)
  Skipped:  <N pages checked, no changes needed>

Instructions

On init (or no wiki exists):

Execute ALL steps below. Do not skip any.

Step 1: Project Discovery

Before creating the wiki, perform a thorough survey of existing project state. The goal: seed the wiki with real content from day one. An empty wiki has no gravity — nobody will maintain it. A wiki with useful content gets maintained.

1a. Read project documentation:

• CLAUDE.md — project rules, architecture notes, operational conventions
• README.md, docs/ — project purpose, architecture, setup instructions
• LAB_NOTEBOOK.md — decisions, findings, experiment history (if exists)
• LEARNINGS.md, PROGRESS.md — distilled knowledge (if exists)
• Any *PLAN*.md, *SPEC*.md, *DESIGN*.md files

1b. Read project metadata:

• package.json, pyproject.toml, Cargo.toml, go.mod, *.csproj — dependencies, project name, scripts
• Configuration files — .env.example, tsconfig.json, docker-compose.yml, etc.
• git log --oneline -20 — recent activity, active areas

1c. Survey project structure:

• Directory layout — identify major components, modules, services
• Entry points — src/index.*, src/main.*, app.*, __main__.py
• Test infrastructure — tests/, __tests__/, test config files

1d. Extract durable knowledge: While reading, actively extract:

• Architecture patterns — how components relate, data flow, key interfaces
• Technology decisions — what was chosen and why (from CLAUDE.md rules, commit messages, config)
• Domain concepts — business rules, terminology, domain-specific logic
• Integration details — external APIs, services, dependencies, their configuration
• Operational knowledge — deployment, monitoring, troubleshooting patterns

If an existing wiki/ directory with index.md is found: Do NOT recreate. Report to the user and redirect to /wiki status.

Step 2: Create Directory Structure

Create the following structure in the project root:

wiki/
├── index.md              # Content catalog organized by category
├── log.md                # Append-only chronological record
├── schema.yaml           # Wiki configuration and conventions
├── README.md             # Human-readable usage guide
├── sources/              # Human-curated raw documents (immutable)
│   └── .gitkeep
└── pages/                # LLM-generated wiki pages
    └── .gitkeep

Step 3: Generate schema.yaml

Create wiki/schema.yaml with smart defaults:

version: 1

categories:
  - architecture     # System design, component relationships, data flow
  - decisions        # Key choices with rationale and alternatives
  - concepts         # Domain concepts, glossary, terminology
  - entities         # Services, tools, teams, external systems
  - integrations     # APIs, dependencies, external system interfaces
  - operations       # Deployment, monitoring, runbooks, troubleshooting
  - reference        # Config values, standards, lookup tables

naming:
  convention: kebab-case
  extension: .md

page_frontmatter:
  required: [title, category, created, updated]
  optional: [sources, related, tags]

maintenance:
  auto_update_triggers:
    - architecture_decisions
    - new_integrations
    - significant_code_changes
    - debugging_insights
    - dependency_changes
    - domain_knowledge
  lint_interval_days: 7
  staleness_threshold_days: 30

Users can edit this file later to add project-specific categories, adjust thresholds, or change conventions.

Step 4: Seed Initial Pages

Based on Step 1 discovery, create 3-8 initial wiki pages in wiki/pages/. Priority order:

1. Project architecture overview — from README + directory structure survey
2. Key decisions — from CLAUDE.md rules, LAB_NOTEBOOK decisions, git history
3. Technology stack — from package files, configs, detected frameworks
4. Domain concepts — from any domain-specific docs, business rules, terminology
5. Active integrations — from config files, API references, docker-compose
6. Operational patterns — from deployment scripts, CI/CD, monitoring setup

Each page must have complete YAML frontmatter:

---
title: Page Title
category: architecture
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: []
related:
  - pages/related-page.md
tags: [relevant, tags]
---

Quality bar for seeded pages: Each page should contain enough information that a new Claude session reading it would learn something useful. Don't create placeholder pages with just a title — write substantive content based on what you discovered. If you can't write at least 3-4 meaningful paragraphs about a topic, it doesn't need its own page yet.

Cross-references: As you create pages, add bidirectional links in the related frontmatter and in the content body. Every page should link to at least one other page.

Step 5: Generate index.md

Create wiki/index.md populated with the seeded pages:

# Wiki Index

> Auto-maintained by Claude. Updated on every page create/update/delete.
> Last lint: never

## Architecture
- [Project Architecture](pages/project-architecture.md) — High-level system design and component relationships

## Decisions
- [Technology Choices](pages/technology-choices.md) — Key technology decisions with rationale
_...etc for each seeded page..._

## Concepts
_No pages yet._

## Entities
_No pages yet._

## Integrations
_No pages yet._

## Operations
_No pages yet._

## Reference
_No pages yet._

---
**Stats:** N pages across 7 categories

Include a section for every category from schema.yaml, even if empty. Populate with actual seeded pages where they exist.

Step 6: Generate log.md

Create wiki/log.md with the initialization entry:

# Wiki Log

> Append-only chronological record. Parseable by prefix.
> Verbs: `create` | `update` | `delete` | `ingest` | `lint` | `query`

## [YYYY-MM-DD] create | Wiki initialized
Seeded N pages from project discovery.
Pages created: page-1.md, page-2.md, page-3.md, ...
Categories populated: architecture, decisions, ...

Step 7: Generate wiki/README.md

Read references/wiki-readme-template.md (relative to this plugin's directory) and emit its template content verbatim as wiki/README.md.

Step 8: Inject CLAUDE.md Section

Append the following section to the project's CLAUDE.md. If no CLAUDE.md exists, create one with this section. If one exists, append at the end.

Before injecting: Check that no existing ## Project Wiki section is already present. If found, skip injection and report to the user.

The section to inject: Read references/claude-md-wiki-section.md (relative to this plugin's directory) and emit its template content verbatim.

Step 9: LAB_NOTEBOOK.md Integration

If the project has a LAB_NOTEBOOK.md, append the following to the CLAUDE.md wiki section (after Rule 7):

### Lab Notebook to Wiki Pipeline
When LAB_NOTEBOOK.md entries contain findings that represent durable, reusable
knowledge (not ephemeral session state), distill those findings into wiki pages.
The notebook captures raw experiments; the wiki captures distilled understanding.
Periodically review recent notebook entries and extract wiki-worthy content.

Step 10: Verify Setup

After creating all files, confirm:

1. wiki/ directory exists with: index.md, log.md, schema.yaml, README.md, sources/, pages/
2. wiki/index.md is populated with seeded pages (not just empty category placeholders)
3. wiki/pages/ contains the seeded page files with valid YAML frontmatter
4. wiki/schema.yaml has all 7 categories and maintenance config
5. CLAUDE.md has the ## Project Wiki — Persistent Knowledge Base section with all 7 rules
6. If LAB_NOTEBOOK.md exists, the pipeline section was added

Step 11: Report to User

Print a summary:

Wiki initialized.

  Directory:  wiki/ created with sources/, pages/, index, log, schema, README
  Pages:      N pages seeded from project discovery
              - Page Title 1 (category)
              - Page Title 2 (category)
              - ...
  CLAUDE.md:  7 wiki maintenance rules injected
  Notebook:   [Lab notebook pipeline added | No LAB_NOTEBOOK.md found]

Next steps:
  - Drop source documents into wiki/sources/ and run /wiki ingest <path>
  - Ask questions with /wiki query <topic>
  - Check health with /wiki lint
  - View stats with /wiki status
  - Customize categories and thresholds in wiki/schema.yaml

On status (wiki already exists):

Redirect to /wiki status. If the /wiki skill is available, invoke it. Otherwise, provide a basic status report:

1. Count pages by category
2. Show last 5 log entries
3. Check if CLAUDE.md wiki section exists

Relationship to Existing Documentation

The wiki doesn't replace other documentation patterns — it complements them:

Design Principles

• Seeded, not empty. The wiki starts with useful content from project discovery. Empty scaffolds don't get maintained.
• Judgment, not mandates. Wiki update rules are judgment calls ("wiki-worthy"), not blocking preconditions. Over-triggering floods the wiki with noise.
• Per-project scope. Each project gets its own wiki. Cross-project knowledge belongs in the memory system.
• Git-tracked. The entire wiki is version-controlled. Review wiki changes in PRs, revert bad updates, track knowledge evolution.
• LLM-owned pages. Humans should not hand-edit wiki/pages/. Let Claude maintain consistency. Report errors to Claude and it will fix pages plus cross-references.
• Human-owned sources. Files in wiki/sources/ are immutable input. Claude reads but never modifies.

Error Handling

• init invoked but wiki/index.md already exists: do not recreate — report to the user and redirect to /wiki status (see Step 1).
• ## Project Wiki section already present in CLAUDE.md: skip injection and report to the user rather than duplicating the section (see Step 8).
• Project has too little discoverable content to seed a meaningful page (can't write 3-4 substantive paragraphs on the topic): skip that page rather than creating a placeholder (see Step 4 quality bar).
• No LAB_NOTEBOOK.md in the project: skip the Lab Notebook pipeline injection (Step 9) and report "No LAB_NOTEBOOK.md found" in the final summary — this is expected, not an error.
• Maintenance mode triggered but no wiki pages relate to the changed source: report "no changes needed" for that source instead of forcing an update.