LLM Wiki Management

Maintain a local, compound-growth knowledge base following Karpathy's LLM Wiki Design Philosophy: Users only need to read, provide materials, and ask questions, while the LLM handles "boring parts" like summarization, cross-referencing, archiving, and bookkeeping. The key difference from various cloud wiki skills is local files + three-layer discipline — versus cloud MCP single-layer documents.

This skill delivers three components:

SKILL.md (this document) — The "constitution" of workflows and disciplines
Deterministic Execution (managed by llmw CLI,
llmw.content
) — This skill has zero code. All deterministic tools in the original scripts/ (lint/ fixtures check/ ingest detection/ mechanical writing) are consolidated into
```
llmw
```
subcommands:
```
llmw wiki lint / check-fixtures / ingest-diff / write
```
(see workflow sections for details). High-frequency deterministic tasks are solidified in the CLI, and agents only handle parts requiring judgment.
references/ — Load on demand: detailed processes for each operation (ingest/ query/ lint/ upgrade), page templates (page-templates.md), lint-checklist, external-repo (access + cross-host reconstruction). Skeleton templates + fixtures (CLI byte-level comparison golden standard) are built into CLI package assets (detected via
```
llmw wiki check-fixtures
```
), and upgrade-workflow.md §6 (semantic merge rules, the basis for agents when following upgrade plans)

Input / Output

Information Required at Startup

Information	Source	Notes
Wiki root directory	`LLM_WIKI_ROOT` environment variable, or interactive query	Example: `~/wiki/llm-systems`
Topic name	Specified once during setup, written to `AGENTS.md`	Example: "LLM Systems"
Operation type	User's natural language	ingest / query / lint / upgrade / setup
Trigger materials	File path or directory during ingest	Must be within `raw/`

Operation Products

setup → Completed by workspace CLI (rendered from templates in the CLI package), this skill does not implement creation logic; products include directory structure + AGENTS.md (SSOT) + CLAUDE.md (thin shell) + wiki/index.md + wiki/log.md + MEMORY/MEMORY.md + .gitignore
ingest → Add/update
```
wiki/sources/<slug>.md
```
+ sync entity/concept pages + append entries to
```
log.md
```
+ update
```
index.md
```
query → Provide answers in the conversation (with references), optionally archive answers as
```
wiki/comparisons/
```
or
```
wiki/syntheses/<slug>.md
```
lint → Report in
```
log
```
: whether raw/ has been modified, orphan pages, broken cross-references, outdated summaries, missing frontmatter, log.md format issues
upgrade →
```
llmw wiki upgrade
```
(dry-run →
```
--apply --yes
```
) fixes the skeleton (byte/block/header-owned + legacy paths); legacy frontmatter of content pages is fixed via
```
lint --check-version --apply
```
to get
```
actions[]
```
, and agents modify according to upgrade-workflow.md §6; see §5 Upgrade for details

Execution Principles / Boundaries

Core Principles

Operation Preprocessing (orient ritual, applicable to all operations): Before starting any ingest/ query/ lint operation, do not rely on symlinks — read the four components in the following order before taking action:
Confirm
<wiki-root>/AGENTS.md
is in context (loaded via thin shell CLAUDE.md or natively — persistent in the session;
CLAUDE.md
is a thin shell of
@AGENTS.md
and does not hold disciplines) — obtain the wiki's topic name and "current configuration" table ("Wiki Format Version" row). The full MEMORY content is already in context via the top
@MEMORY/MEMORY.md
@import
; tag whitelist is in
wiki/tags.md
(see §Core Principles §6)
Read <$LLM_WIKI_ROOT>/wiki/index.md
— Know which pages exist and their categories, avoid duplicate creation/ missing cross-references
Read <$LLM_WIKI_ROOT>/wiki/log.md
(last ~30 lines are sufficient) — Review recent activities, avoid duplicate ingest/ missing archiving of old work
Read <$LLM_WIKI_ROOT>/scripts/SCRIPTS.md
(as needed) — Confirm whether this wiki has a complete section contract for project-level extended scripts (usage scenarios/ calling conventions/ functions/ preconditions); not mandatory (wiki may not have scripts/), but must check before triggering non-standard workflows (the
@scripts/SCRIPTS.md
@import
at the top of AGENTS.md has loaded the full content)
Do not write any wiki content if any of the four components are not read. For wikis with 100+ pages, also run
Grep "<topic>"
across the entire
wiki/
directory — relying solely on index.md may miss reference relationships between entity/concept pages.

raw/ is controlled by users, LLM has read-only access — Two write permission exceptions (
```
raw/external/
```
symlink access +
```
raw/discussions/
```
collaborative drafts) cannot be extended; see
```
references/external-repo.md
```
/
```
references/ingest-workflow.md §10
```
for operation details
Standard write operations =
llmw wiki write
series — Append logs via
```
write log
```
, create new pages via
```
write new
```
, clear the
```
reviewed
```
timestamp after editing approved pages via
```
write touch
```
, add new MEMORY entries via
```
write memory add
```
, add index entries via
```
write index add
```
; format +
```
LOG_RETENTION_LIMIT
```
truncation are guaranteed by scripts, and lint only handles manual modifications outside the standard path. Escape hatch: Manual Edit/Write is allowed for formats not supported by scripts, with lint as a fallback — scripts are the default path, not a gatekeeper
Every page must have YAML frontmatter — create new pages via
llmw wiki write new
(5 required fields + recommended
```
description
```
). Authoritative definitions (values of
```
type
```
/ reserved fields/
```
sources
```
specialization/ credibility signals) are in
```
references/page-templates.md
```
§1; exception list (index/ log/ MEMORY/ MEMORY*) is in the same section
LLM must clear the
reviewed
timestamp when modifying approved pages — Run
```
llmw wiki write touch
```
after each edit; canonical lifecycle rules are in the "Credibility and Cognitive Quality Signals" section of
```
page-templates.md
```
; lint uses
```
reviewed-stale
```
as a fallback
MEMORY/ is the private memory of LLM agents — Add new entries via
```
llmw wiki write memory add
```
; only modify
```
MEMORY/MEMORY.md
```
(no copy drift). Its physical location in
```
<wiki-root>/
```
instead of
```
wiki/
```
means it is naturally kept as a private layer and not published during publishing; see Workflow §4 for writing process
Tag whitelist is in
wiki/tags.md
— Canonical values/ parsing/ audit cycle are explained in the header block of the fixture (read immediately after being written to disk); lint semantics are in
```
lint-checklist.md §11
```

Boundaries

Do not bypass
AGENTS.md
to create custom conventions — If AGENTS.md does not specify, ask the user first before writing

Other boundary disciplines are subject to
AGENTS.md
in the wiki root (automatically loaded, persistent in the session).

Anti-Patterns (Absolutely Forbidden)

Cross-wiki references without updating the index of the target wiki (synchronization is the user's responsibility)

Other anti-patterns are subject to
AGENTS.md
in the wiki root +
references/external-repo.md
§5.

Anti-Rationalization Triad (Mandatory for Discipline-Based Skills)

This skill is a discipline-based skill (contains multiple "must/ forbidden/ not" + sections starting with "not"). Discipline-based prohibitions may be bypassed by the LLM under pressure with various rationalizations — the triad only blocks one type: rationalized violations. Unrationalized violations (directly ignoring rules) mean the anti-pattern list itself is incomplete, and are unrelated to the triad.

Rationalization Table

Baseline actual run records: 3 RED runs — ① Disciplined ingest task: fully compliant with zero excuses; ② Undisciplined ingest task (Iron Law creation scenario): still compliant (the model has built-in knowledge of the规范); ③ Disciplined + user-pressured task ("Just jot it down/ hurry up"): produced one real excuse (row 1 in the table below) + one silent omission (missing required
tags
field in frontmatter, omitted directly without excuse).

Common Excuse	Why It's Wrong	What to Do Instead
"The clipping only has one sentence, following the 'restrained page creation' principle and your advice to handle small matters lightly, one source page is enough" (actual run transcript)	The user's "casual/ hurry up" is an attitude, not an exemption — creating a wiki page triggers the 5 required fields/ page creation threshold/ log disciplines; "handling lightly" uses the user's emotion as an excuse to skip disciplines (the same run also silently omitted the required `tags` field)	Do not shrink the process; execute the "restrained page creation" judgment truthfully but explain to the user ("This document only has one central topic, no concept page will be created for now, and it will be added when a second document on the same topic appears"), and follow the field and log disciplines as required

Inclusion Rule: Entries in the table are only collected from actual run transcripts (pre-written excuses = noise + signal interference; consistent with the "anti-rationalization" principle). The table currently has only 1 row (3 RED runs produced only 1 real excuse + 1 silent omission); new excuses from future actual runs will be added to the table, and no entries will be added if they do not appear.

Violating the Letter = Violating the Spirit

Any workaround that "looks different but has the same effect" for the prohibitions in §Core Principles/ §Boundaries/ §Anti-Patterns is considered a violation — the top three common workarounds for this skill:

Changing
```
Edit
```
/
```
Write
```
to
```
Read
```
+ manually generating new content then
```
Write
```
— does not bypass the prohibition of "using tools other than Read for automatic modification", using Write as the operation tool still counts
Interpreting "do not delete wiki pages" as "copy the content out first, then
```
rm
```
, then write it back" — does not bypass the no-deletion prohibition, the state effect is exactly the same
Interpreting "raw/ is controlled by users, LLM has read-only access" as "I
```
cp
```
into raw/ then immediately
```
rm
```
, I read the content in the window = equivalent to read-only" — does not, writing occurs in the first step

Forbid using "strictly literal/ strictly spiritual" alternative wording to leave loopholes for agents — any "looks different but has the same effect" is a violation.

Red Flags (Thought List — Stop Immediately When They Appear)

Having a thought ≠ having violated a rule; thoughts = warnings = re-read §Core Principles/ §Boundaries/ §Anti-Patterns.

"The user said 'Just jot it down/ hurry up/ don't be too formal' — disciplines can be relaxed" (actual run observation)
"I think this step is unnecessary for the current case"
"The user didn't explicitly ask me to do this step"
"This is faster/ saves more tokens/ is more efficient"
"The convention doesn't prohibit it"
"I've done something equivalent" / "Same effect doesn't count as a violation"
"Leave it like this for now, I'll fix it later"
"Generating fields myself is more flexible than writing strictly according to frontmatter"
"Skip the log entry this time, it's a wiki not git anyway"
"The user modifies raw/ every day, I'll help out"
"Lint reported a lot of issues, but they're all warnings so they don't count as errors"

There is no progression of "thought list = violation" — having a thought is a signal, and continuing to act will lead to a violation. But continuing after having a thought = assuming responsibility for violating the spirit.

Workflows / Steps

0. One-Time Setup (First Use) — Completed by Workspace CLI

Responsibility Boundary: This skill only handles the growth phase of the wiki (ingest/ query/ lint). The creation and deletion of wiki repositories are handled by the workspace CLI — the command is
llmw
(maintained in the same repository as this skill, see its built-in documentation for command names and parameters); the "birth form" of the wiki repository is determined by template rendering in the CLI package — detected via
llmw wiki check-fixtures
. See §Input/Output Operation Products for product forms.

What LLM agents do after taking over:

Verify CLI deployment — Read
```
<wiki-root>/AGENTS.md
```
to confirm the topic name and date are replaced correctly;
```
wiki/index.md
```
/
```
wiki/log.md
```
exist and have complete frontmatter;
```
<wiki-root>/CLAUDE.md
```
is a thin shell
Run the orient ritual (see the quoted block at the top of §Execution Principles / Boundaries)
Ask the user if they want to do the first ingest — if yes, provide the path of the first material to the agent

1. Ingest (Ingest New Materials)

Triggers: "Ingest this into the wiki" / New files in

raw/

/ Running

llmw wiki ingest-diff

finds uningested items.

Process Summary (agent-driven; detailed 7 steps + batch processing in

references/ingest-workflow.md

; 5-step access/ drift refresh/ cross-host reconstruction for external code repositories in

references/external-repo.md

Run
```
llmw wiki ingest-diff
```
(add
```
--check-stale
```
for daily use) to find the list of uningested/ re-ingestable files
Verify key points for single files — Only for interactive single-file or small-scale scenarios: confirm topic direction/ key cross-referenced entities/ user's judgment on what to retain
For each file: Read the full text → Extract metadata → Create a skeleton via
```
llmw wiki write new --type=source ...
```
→ Write the body (use Edit instead of Write overwrite for stale-raw) → Sync entity/concept pages (only append the "Sources" section) →
```
llmw wiki write index add
```
→
```
llmw wiki write log --op=ingest
```
→ Run
llmw wiki write touch
for edited pages
commit (only when git is enabled): Rhythm is determined by the user/agent, do not auto-commit

Batch Ingest (≥ 3 raw materials ingested simultaneously)

Use the batch processing path instead of processing one by one. Aggregate once, write once, index once — avoid N repeated searches/ N index updates/ N log entries. See the "Batch Processing" section of

references/ingest-workflow.md

for details on the 5-step process/ why batch processing/ log title prefix

Bulk:

External code repositories as corpus — If the user says "Include repo X in the wiki": do not embed or copy the repository, use the symlink path in

external-repo.md

(one of the write permission exceptions to the raw/ core discipline — symlinks + anchors are always written via the

llmw wiki external

CLI subcommand; the other exception is

raw/discussions/

collaborative drafts, see ingest-workflow.md §10). Access command:

llmw wiki external add <target> --name=<n> [--notes=...]

(CLI automatically creates symlinks + reads git identity fields + atomically writes anchors); then run

llmw wiki ingest-diff

to scan; see

references/external-repo.md

for drift refresh/ cross-host reconstruction (

llmw wiki external rebuild

2. Query (Cross-Page Synthesis)

Triggers: "Does the wiki have X?" / "Summarize content about Y in the wiki" / "Compare A and B".

Process:

Check index.md first — Find candidate pages by keywords/ categories
Read relevant pages (do not read raw/ — raw/ has already been digested in source pages)
Cross-page synthesis — Include source links in reference format; explicitly mark contradictions: "A states X (Source: ...), B states Y (Source: ...), further research is needed"
Display answer + ask about archiving — If the answer has the nature of "comparison/ synthesis/ discovering connections", ask the user: "Is this answer suitable for archiving back to the wiki as comparisons/
```
<slug>
```
.md?"
Archive after user approval — Use the
```
comparison
```
or
```
synthesis
```
template from references/page-templates.md + append a log entry

See

references/query-workflow.md

for detailed query processes and judgment rules.

3. Lint (Health Check)

Triggers: "Lint the wiki" / Regularly (frequency threshold in lint-checklist.md §7) / Proactively suggest for large wikis.

Process:

Run
```
llmw wiki lint
```
for deterministic checks
Script coverage (major categories below, authoritative list in
```
references/lint-checklist.md
```
): raw immutability/ frontmatter fields/ orphan pages/ broken links/ log.md format/ outdated summaries/ page volume/ cognitive quality and credibility signals (
```
reviewed
```
/
```
contested
```
/
```
contradictions
```
) /
```
raw/external/
```
symlink ↔ anchor association (external-repo.md)/ fixture consistency (see the "Fixture Consistency Check" section below)
After script output, agents must also perform semi-qualitative checks: contradictory claims/ missing cross-references/ suggestions for new ingest directions
Report + ask the user which fixes to implement

See

references/lint-checklist.md

for detailed checklists.

4. Memory (Write to LLM Agent's Persistent Memory)

Triggers: Identify information worth沉淀 during ingest/ query/ lint processes — pitfalls, user preferences, cross-document associations.

When to Write:

Encountering pitfalls (e.g., frequent OCR errors in raw/ PDFs, ask the user to convert the format first next time)
Discovering user preferences (e.g., user prefers tabular comparisons, dislikes prose-style summaries)
Cross-ingest associations (two source pages point to different chapters of the same paper)
Recurring patterns in lint reports (every lint reports missing fields for a certain type)

Process Summary (agent-initiated; authoritative definitions of frontmatter fields/ index synchronization/ full vs short entry judgment are in the

MEMORY/

section of

AGENTS.md

in the wiki root + the header block of fixture

memory-index.txt

Decide if it's worth writing — Will it make future agent work smoother?
Determine entry form: Full (includes why+how context) → Create a file + index entry via
```
llmw wiki write memory add --slug=... --title=...
```
, then Edit to write the body; Short (pure reminder) → Directly add an index line to
```
MEMORY/MEMORY.md
```
Write the body — Record specific experience, including context/ solution steps/ how to avoid it in the future
Do not append log entries/ do not list in wiki/index.md (MEMORY does not follow the single-entry constraint)

Disciplines:

Do not delete any MEMORY files — Pitfall records are preserved
Retain the original
```
created
```
field when writing new files; only update
```
updated
```
Users do not directly edit MEMORY/ — If the user wants to add content, inform the agent first and let the agent write it

5. Upgrade (Upgrade Wiki Format)

Triggers: User says "Upgrade the wiki/ migrate/ check wiki version/ old format/ format upgrade/ need reformat"; or

llmw wiki lint

reports

wiki-format-version-stale

/ legacy warnings.

Responsibilities: Three-party division of labor — CLI

llmw [wiki] upgrade

fixes the skeleton (byte/block/header-owned + legacy paths + self-verify + blocked_drift 3 final states); lint plan

actions[]

fixes legacy frontmatter of content pages (currently only

type-memory-value

); agents are responsible for drift adjudication (retain or discard local custom MEMORY) + §6 semantic merging (index duplication/ MEMORY merging). Do not use

llmw wiki write

during migration; do not append log entries.

Complete Steps (5-step process/ drift adjudication/ decision tree/ semantic merge rules §6.1-§6.4) are in

references/upgrade-workflow.md

Reference Examples

5 complete examples (setup/ ingest/ query/ lint/ upgrade) are in

references/examples.md

— Read as needed.

yzr-llm-wiki-management

NPX Install

Tags

SKILL.md Content (Chinese)