# Create Wiki

> Set up a persistent, LLM-maintained wiki inside any project. Creates a wiki/ directory with sources, pages, schema, and navigation files, seeds initial pages from project discovery, and injects CLAUDE.md rules that make Claude automatically maintain the wiki during normal work sessions. Suggest when — project accumulating complexity, context loss between sessions, multiple contributors, "I keep forgetting", significant domain knowledge, or LAB_NOTEBOOK.md with durable insights. Confirms before writing anything when suggested rather than invoked.

- Skill: `davistroy/create-wiki` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davistroy/create-wiki`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davistroy/create-wiki/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: davistroy (https://skillmd.com/u/davistroy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davistroy/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`:

```json
{
  "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:

```text
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:
```bash
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](../../../../docs/adr/0012-artifact-derived-documentation.md)). So identify
changed sources from git:

```bash
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:
```text
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:

```text
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:

```yaml
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:

```yaml
---
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:

```markdown
# 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:

```markdown
# 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):

```markdown
### 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:

```text
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:

| Existing pattern | Relationship to wiki |
|-----------------|----------------------|
| `LAB_NOTEBOOK.md` | Notebook captures raw experiments and ephemeral state. Wiki captures distilled, durable knowledge. Periodically extract insights from notebook into wiki pages. |
| `LEARNINGS.md` | Learnings captures distilled wisdom from sessions. Wiki organizes knowledge by topic with cross-references. They can coexist — learnings is linear, wiki is structured. |
| `PROGRESS.md` / session handoffs | Progress tracks session-level work. Wiki tracks project-level knowledge. Wiki-worthy findings from progress notes should become wiki pages. |
| `README.md` | README is the public-facing entry point. Wiki is the deep internal reference. README stays concise; wiki goes deep. |
| Git commit messages | Commits record what changed. Wiki records what we know and why. |
| `CLAUDE.md` | CLAUDE.md has operational rules. Wiki has knowledge. The CLAUDE.md wiki section tells Claude how to maintain the wiki; the wiki itself holds the knowledge. |
| Memory system (MEMORY.md) | Memory is cross-project, cross-session. Wiki is per-project, durable knowledge. Memory remembers user preferences and project context; wiki remembers how the system works. |

## 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.