create-wiki

What this skill does

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

## Proactive Triggers

Suggest this skill when:
1. A project is accumulating complexity — multiple integrations, services, or domain-specific concepts
2. Context is being lost between sessions — the same questions keep coming up
3. Multiple sessions or people are working on the same project
4. The user mentions "I keep forgetting..." or "what was that decision about..."
5. A project has significant domain knowledge that isn't captured in code comments or README
6. LAB_NOTEBOOK.md entries contain durable knowledge that deserves a more structured home

**Do NOT fire when:**
- A `wiki/` directory already exists with an `index.md` — redirect to `/wiki status` instead
- The project is trivial (single file, no domain complexity)
- The user explicitly declines structured knowledge management

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

## 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 `paths:` auto-activation fires (a source file or CLAUDE.md changed) OR when the user invokes with `status`.

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

#### Maintenance Step 1: Identify Changed Sources

Determine what triggered the skill (if auto-activated via `paths:`):
- If triggered by `wiki/sources/**/*` — a source file was added or modified
- If triggered by `CLAUDE.md` — project rules changed; wiki pages covering architecture or conventions may be stale
- If triggered by `LAB_NOTEBOOK.md` — new findings may be wiki-worthy; check for extractable durable knowledge
- If invoked directly — check recent git changes: `git diff --name-only HEAD~1 HEAD`

#### 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, ad