SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsyzr-llm-wiki-management

yzr-llm-wiki-management

Writing & research

View repository

Updated 10-16 09:30

About this skill

LLM Wiki Management

Per Karpathy LLM Wiki design philosophy Maintain alocal、compoundingknowledge base: the user only reads + provides materials + asks questions, and the LLM handles the "boring parts" such as summarizing, cross-referencing, archiving, and bookkeeping. The key difference from various cloud wiki skills is local files + three-layer discipline—vs cloud MCP single-layer documents.

This skill provides three deliverables:

  • SKILL.md (this document)—the "constitution" of workflows + discipline
  • Deterministic execution (assigned to the llmw CLI,llmw.content）—this skill zero code. The deterministic tools from the original scripts/ (lint / fixtures check / ingest detection / mechanical writes) are all consolidated into llmw subcommands:llmw wiki lint / check-fixtures / ingest-diff / write(see §Workflow sections for details). High-frequency deterministic tasks are codified in the CLI, and the agent is only responsible for the parts requiring judgment.
  • references/—loaded on demand: detailed processes for each operation (ingest / query / lint / upgrade), page templates (page-templates.md), lint-checklist, external-repo (onboarding + cross-host rebuild). Skeleton templates + fixtures (the CLI byte-level comparison gold standard) are built into the CLI package assets (llmw wiki check-fixtures detection), upgrade-workflow.md §6 (semantic merge rules, the merge basis for the agent when following an upgrade plan)

Inputs / outputs

Information required at startup

Information Source Notes
Wiki root directory LLM_WIKI_ROOT environment variable, or ask interactively e.g. ~/wiki/llm-systems
Topic name specified once at setup, written to AGENTS.md e.g. "LLM Systems"
Operation type User natural language ingest / query / lint / upgrade / setup
Triggering material during ingest, provide a file path or directory must be within raw/ inside

Operation artifacts

  • setup → completed by the workspace CLI (written to disk according to templates in the CLI package), this skill does not implement creation logic; artifact form is 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 log.md entries + update index.md
  • query → give the answer in conversation (with citations),Optionalarchive the answer as wiki/comparisons/ or wiki/syntheses/<slug>.md
  • lint → log report in: whether raw/ was modified, orphan pages, broken cross-references, stale summaries, missing frontmatter, log.md format
  • upgrade → llmw wiki upgrade（dry-run → --apply --yes) fix the skeleton (byte/block/ header-owned + legacy paths); content page frontmatter legacy goes through lint --check-version --apply get actions[], the agent fixes according to references/upgrade-workflow.md §6; see §5 Upgrade for details

Execution principles / boundaries

Core principles

Operation preconditions (orient ritual, common to all operations): before every ingest / query / lint startup,does not rely on symlink ——read the four-piece set in the following order before acting:

  1. Confirm <wiki-root>/AGENTS.md is already in context(via the thin-shell CLAUDE.md or native loading——persistent for the session;CLAUDE.md is @AGENTS.md thin shell, holds no discipline)——get this wiki's topic name and the "current configuration" table (Wiki Format 版本 row). The full MEMORY text via the top @MEMORY/MEMORY.md @import is already in context; the tag whitelist is in wiki/tags.md(see §Core Principles §6)
  2. Read <$LLM_WIKI_ROOT>/wiki/index.md——know which pages exist and which categories they are distributed in, to avoid duplicate creation / missed cross-references
  3. Read <$LLM_WIKI_ROOT>/wiki/log.md(the most recent ~30 lines suffice)——see recent activity clearly, to avoid duplicate ingest / missed archiving of old work
  4. Read <$LLM_WIKI_ROOT>/scripts/SCRIPTS.md(as needed)——confirm whether this wiki has project-level extension scripts'complete section contract(usage scenarios / invocation conventions / purpose / prerequisites); not mandatory (a wiki may have no scripts/), butbefore triggering a non-standard workflowyou must check first (the @scripts/SCRIPTS.md @import at the top of AGENTS.md has already loaded the full text)

If any of the four-piece set has not been fully read, do not write any wiki content. A wiki with 100+ pages should also, in wiki/ the entire Grep "<topic>" supplement once——looking only at index.md may miss reference relationships between entity/concept pages.

  1. raw/ is controlled by the user, the LLM only reads——the two write-permission exceptions (raw/external/ symlink access + raw/discussions/ collaborative drafts) must not be extrapolated; for operational details see references/external-repo.md / references/ingest-workflow.md §10
  2. The proper path for write operations = llmw wiki write series——log appends go through write log, new page creation goes through write new, after editing a reviewed page clearing the reviewed stamp goes through write touch, new MEMORY entries go through write memory add, index entries go through write index add; format + LOG_RETENTION_LIMIT truncation is guaranteed by the script, lint only catches out-of-band manual edits.Escape hatch: for forms not supported by the script, handwritten Edit/Write is legitimate, with lint as a fallback——the script is the default path, not a gate
  3. Every page must carry YAML frontmatter——new page creation goes through llmw wiki write new(5 required + recommended description). Authoritative definition (type values / reserved / sources specialization / credibility signals) see references/page-templates.md §1; the exception list (index / log / MEMORY / MEMORY*) is in the same section
  4. When the LLM modifies a reviewed page it must clear the reviewed stamp——after every edit run llmw wiki write touch; for lifecycle rules canonical see page-templates.md the "Credibility and Cognitive Quality Signals" section; lint uses reviewed-stale as a fallback
  5. MEMORY/ is the LLM agent's private memory——new entries go through llmw wiki write memory add; only modify MEMORY/MEMORY.md this one copy (no copy drift). Its physical location is in <wiki-root>/ rather than wiki/ inside = at publish time it is naturally kept as a private layer and not shared externally; for the write process see Workflow §4
  6. The tag whitelist is in wiki/tags.md——values / parsing / audit loop canonical is in the fixture header explanation block (read upon landing on disk); for lint semantics see lint-checklist.md §11

Boundary

  • Do notbypass AGENTS.md to invent conventions——if AGENTS.md does not say it,Ask the user firstthen write

The remaining boundary discipline is governed by the wiki root AGENTS.md (auto-loaded, resident for the session).

Anti-patterns (strictly prohibited)

  • Cross-wiki mutual references without updating the counterpart's index (synchronization is the user's responsibility)

The remaining anti-patterns are governed by the wiki root AGENTS.md + references/external-repo.md §5.

The anti-rationalization trio (mandatory for discipline-type skills)

This skill is a discipline-type skill (containing multiple "must / prohibited / do not" + "do not" opening paragraphs). Discipline-type prohibitions will be bypassed under LLM pressure with various rationalization excuses—the trio blocks only one category:violations that have already been rationalized. Unrationalized violations (directly ignoring the rules) = the absence of the §Anti-patterns checklist itself, unrelated to the trio.

Rationalization Table

baseline actual-run record: 3 RED runs—① ingest task with discipline: fully compliant with zero excuses; ② ingest task without discipline (Iron Law creation scenario): still compliant (the model has this normative knowledge built in); ③ task with discipline + user pressure ("just jot it down / in a hurry"): produced one genuine excuse (row 1 of the table below) + one silent omission (frontmatter missing the required tags field, omitted directly without excuse).

Common excuses Why it is wrong What should be done instead
"The clipping is only one sentence; per the 'restrained page creation' principle and what you said about small matters being handled lightly, one resource page is enough" (actual-run transcript) The user's "just casually / in a hurry" is an attitude, not an exemption—writing a wiki page triggers the 5 required fields / page creation threshold / log discipline; "handling lightly" uses the user's emotions as a shield for omitting discipline (in the same turn, the required tags field was also silently omitted) The process is not reduced; the "restrained page creation" judgment is executed faithfully butexplained to the user("This article has only one central topic; no concept page will be created for now; when a second article on the same topic appears, it will be added"), while field and log discipline proceed as usual

Inclusion discipline: entries in the tableonlyare included from actual-run transcripts (pre-written excuses = noise + signal interference; consistent with the "anti-rationalization" principle). This table currently has only 1 row (3 RED runs produced only 1 genuine excuse + 1 silent omission); new excuses appearing in future actual runs are added to this table, and none are added if none appear.

Violating the letter = violating the spirit

Any "looks different but has the same effect" circumvention of the three prohibition sections §Core Principles / §Boundaries / §Anti-patterns counts as a violation—the top three common circumventions for this skill:

  • Changing Edit / Write to Read + manually generating new content and then Write——does not count ascircumventing the "use tools other than Read to make automatic modifications" prohibition; if the operating tool is Write, it still counts
  • Interpreting "do not delete wiki pages" as "first copy the content out and then rm and then write it back"—does not count ascircumventing the no-deletion prohibition; the state effect is completely equivalent
  • Interpreting "raw/ is controlled by the user, the LLM only reads" as "Icp into raw/ and then immediatelyrm, and I read the content in the window = equivalent to read-only"—does not count, the write occurs in the first step

ProhibitedUse "strictly literal / strictly in spirit" either-or wording to leave the agent an out—any "looks different but is equivalent in effect" is a violation.

Red Flags (thought checklist — stop when any appears)

A thought appearing ≠ already violated; thought = warning = reread the three sections §Core Principles / §Boundaries / §Anti-patterns.

  • "The user said 'just jot it down casually / in a hurry / don't be too formal'—discipline can be relaxed" (observed in actual runs)
  • "I think this step isn't necessary for the current case"
  • "The user didn't explicitly say to do this step"
  • "This is faster / saves more tokens / is more efficient"
  • "The agreement doesn't prohibit it"
  • "I've already done the equivalent" / "Same effect doesn't count as a violation"
  • "Leave it like this for now, fill it in later"
  • "Generating fields myself is more flexible than writing them strictly in frontmatter"
  • "Skip the log entry this time, it's a wiki not git anyway"
  • "The user edits raw all the time anyway, let me help out"
  • "Lint reported a bunch, but they're all warns so they don't count as errors"

There is no progression of "thought checklist = already violated"—a thought appearing is asignal, and only continuing further becomesaction. Butcontinuing after the thought = by default taking responsibility for violating the spirit.

Workflow / Steps

0. One-time setup (first use) — done by the workspace CLI

Boundary of responsibility: this skill is only responsible for the wiki'sgrowth stages(ingest / query / lint). The wiki repo'screation and deletionare handled by the workspace CLI—the command is llmw（maintained in the same repo as this skill, see its bundled documentation for the command name and arguments); the wiki repo's "birth form" is determined by rendering the template in the CLI package—llmw wiki check-fixtures detection. For the artifact form see §Input/Output operational artifacts.

What the LLM agent does after taking over：

  1. Verify the CLI wrote to disk—read <wiki-root>/AGENTS.md to confirm the topic name + date substitution is correct; wiki/index.md / wiki/log.md exists and frontmatter is complete;<wiki-root>/CLAUDE.md is a thin shell
  2. Run the orient ritual (see the quoted block at the top of §Execution Principles / Boundaries)
  3. Ask the user whether to do the first ingest—if so, give the agent the path of the first material

1. Ingest (ingest new material)

Trigger: "ingest this into the wiki" / raw/ has new files / run llmw wiki ingest-diff to find un-ingested items.

Process summary(agent-driven; for the detailed 7 steps + batch processing see references/ingest-workflow.md; for external code repo 5-step onboarding / drift refresh / cross-host rebuild see references/external-repo.md）：

  1. Run llmw wiki ingest-diff(add --check-stalefor daily use) to find the list of un-ingested/to-be-re-ingested files
  2. Go over the key points for a single piece—only for interactive single-piece or small-volume scenarios: confirm the topic direction / entities with key intersections / what the user judges should be kept
  3. For each file: Read the full text → extract metadata → llmw wiki write new --type=source ... build the skeleton → write the body (for stale-raw use Edit,do not Write overwrite) → sync entity/concept (only append the "Sources" section) → llmw wiki write index add → llmw wiki write log --op=ingest → run for edited pages llmw wiki write touch
  4. commit(only when git is enabled): the cadence is decided by the user/agent,do notautomatically commit

batch ingestion (≥ 3 raw files ingested at the same time)

takes the batch path rather than one by one.one aggregation, one write, one index—avoid N repeated searches / N index updates / N log entries. For the 5-step process + why batching + the log title prefix Bulk: details, see references/ingest-workflow.mdthe "Batch Processing" section.

External code repositories as corpus—if the user says "bring repo X into the wiki":do notembed-copy the repo; use the external-repo.md symlink path (raw/ one of the write-permission exceptions to theoverall discipline for raw/—symlinks + anchors always go through the llmw wiki external CLI subcommand to be written to disk; the other exception is raw/discussions/ collaborative drafts, see ingest-workflow.md §10). Onboarding command:llmw wiki external add <target> --name=<n> [--notes=...](the CLI automatically creates the symlink + reads the git identity field + atomically writes the anchor); then llmw wiki ingest-diff scans; drift refresh / cross-host rebuild (llmw wiki external rebuild) see references/external-repo.md。

2. Query (cross-page synthesis)

Trigger: "is there X in the wiki" / "summarize what the wiki says about Y" / "compare A and B".

Process：

  1. First look at index.md—find candidate pages by keyword / category
  2. Read the relevant pages(do not read raw—raw has already been digested into the source pages)
  3. Cross-page synthesis—use citation form with source links; explicitly flag contradictions: "A says X (source: ...), B says Y (source: ...), needs deeper investigation"
  4. Present the 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 into the wiki as comparisons/<slug>.md?"
  5. Archive after the user agrees—use the comparison or synthesis template from references/page-templates.md + append a log entry

For the detailed query process and decision rules, see references/query-workflow.md。

3. Lint (health check)

Trigger: "lint wiki" / periodic (for frequency thresholds see lint-checklist.md §7) / proactive suggestion for large wikis.

Process：

  1. Run llmw wiki lint for deterministic checks
  2. Script coverage (major categories below, authoritative list see references/lint-checklist.md): raw immutability / frontmatter fields / orphan pages / broken links / log.md format / stale summaries / page size / cognitive quality and credibility signals (reviewed / contested / contradictions）/ raw/external/ symlink ↔ anchor association (external-repo.md) / fixtures consistency (see the "fixtures consistency check" section below)
  3. After the script outputs, the agent must also do semi-qualitative checks: contradictory claims / missing cross-references / suggested new ingestion directions
  4. Report + ask the user which ones to fix

For the detailed checklist see references/lint-checklist.md。

4. Memory (write to the LLM agent's persistent memory)

Trigger: during ingest / query / lint, identify information worth retaining—pitfalls, user preferences, cross-document connections.

When to write：

  • Encountering pitfalls (e.g., raw/ PDF frequently has OCR errors; next time have the user convert the format first)
  • Discovering user preferences (e.g., the user prefers tabular comparisons and dislikes prose-style summaries)
  • Cross-ingest association (two source pages point to different sections of the same paper)
  • Recurring pattern in lint reports (every lint reports a certain type missing a field)

Process summary(agent-initiated; the authoritative definitions of frontmatter fields / index sync / full vs. short entry determination are in the wiki root AGENTS.md section + fixture MEMORY/ header description block canonical): memory-index.txt Header note block canonical):

  1. Decide whether it is worth writing—can it make future agent work smoother?
  2. Determine the entry form:Full(including why+how context) → llmw wiki write memory add --slug=... --title=... create file + index row, then Edit to write the body;Short(pure reminder) → directly MEMORY/MEMORY.md add an index row
  3. Write the body—record the specific experience, including context / resolution steps / how to avoid it in the future
  4. Do notappend a log entry / Do notlist in wiki/index.md (MEMORY does not follow the single-entry constraint)

Discipline：

  • Do not delete any MEMORY file—pitfall records are accumulated
  • When writing a new file, preserve the original created field; only update updated
  • UserDo notdirectly edit MEMORY/—if the user wants to add something, first tell the agent and let the agent write it

5. Upgrade (upgrade wiki format)

Trigger: the user says "upgrade wiki / migrate / check wiki version / old format / format upgrade / whether reformat is needed"; or llmw wiki lint reports wiki-format-version-stale / legacy warn。

Responsibilities: three-way division of labor—CLI llmw [wiki] upgrade fixes the skeleton (byte/block/header-owned + legacy paths + self-verify + blocked_drift 3 terminal states); lint plan actions[] fixes content page frontmatter legacy (currently only type-memory-value); the agent is responsible for drift adjudication (move local customizations to MEMORY or discard them) + §6 semantic merging (index duplicates / MEMORY consolidation). During migration, do not use llmw wiki write； Do notappend a log entry.

Complete steps(5-step process / drift adjudication / decision tree / semantic merge rules §6.1-§6.4) see references/upgrade-workflow.md。

Reference examples

5 complete examples (setup / ingest / query / lint / upgrade) see references/examples.md—Read as needed.