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

yzr-llm-wiki-management

Agents & models

View repository

Updated 10-16 04:59

About this skill

LLM Wiki Management

Per Karpathy LLM Wiki design philosophy Maintain alocal、compound-interest accumulatingknowledge base: the user only reads + provides materials + asks questions, the LLM handles the "boring parts" like summarization, cross-referencing, archiving, and bookkeeping. The key difference from yzr-outline-wiki and other cloud 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 workflow + discipline
  • scripts/——ingest_diff.py / lint_wiki.py / check_wiki_fixtures.py / log_format.py / wiki_write.py(mechanical byte write operations: the five subcommands log / index / touch / new / memory, see §Design Decisions "mechanical vs judgment" admission rules). High-frequency deterministic tasks are solidified (notincluding setup_wiki—wiki repo creation is handled by the external workspace CLI). For the current number of check items see metadata.fixtures_check_count(see details in references/migrate-workflow.md + §Five Migrate).
  • references/—loaded on demand: AGENTS.md schema template + CLAUDE.md thin-shell template, detailed workflows for each operation, page templates, wiki-spec.md (wiki repo birth form + skill read contract), fixtures (CLI byte-level comparison gold standard), migrate-workflow.md §Six (semantic merge rules, the merge basis when the agent follows a migration plan)

When not to use

"When to use / not applicable" is already in the frontmatter description (including trigger words), the body does not repeat it. This section only supplementsway outand body-exclusive negative examples:

  • Cloud collaborative wiki(Notion / Confluence / Outline Wiki / GitHub Wiki)—use yzr-outline-wiki(search / read / write / edit). The two sets of skills are one-directional: local research accumulation → cloud sharing, no conflict
  • One-off document generation(not accumulation-type)—directly use the ordinary file write workflow
  • No raw/ materials + no accumulation need—the value of the skill lies in "compound interest", one-off organization does not need it
  • Need a strongly structured database(with schema / SQL / full-text search backend)—when the wiki scale ≤ several hundred pages index.md is enough; beyond that scale consider migrating to a dedicated tool
  • Multi-person real-time collaboration—this skill assumes single-person use (multi-account real-time collaboration goes to cloud wiki)
  • System design document writing(single formal design document)—use yzr-sys-design-doc

Input / Output

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 time, written to AGENTS.md e.g. "LLM Systems"
Operation type User natural language ingest / query / lint / migrate / setup
Trigger material provide file path or directory when ingesting must be within raw/ within

Operation artifacts

  • setup → Completed by the external workspace CLI (written to disk per references/wiki-spec.md ), this skill does not implement the creation logic; the artifact forms are a 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 the 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
  • migrate → Run scripts/lint_wiki.py --check-version to output the spec version + legacy status report;--apply output the migration plan as JSON to stdout (not written to disk) for the agent to follow references/migrate-workflow.md via Edit/Write fixes; see §5 Migrate for details

Design decisions

Mechanical vs judgment — admission rules for write operations entering scripts

A write operation enters a script (wiki_write.py), if and only if: (1) the output bytes are a pure function of the input (does not read the body text, no trade-offs, no user preferences);(2) lint already has a corresponding check that can verify the artifact(round-trip verifiable: script artifacts must be lint-clean).If either is missing → leave it to the agent/md. During the migration period, always use the agent (migration = when the format is not yet settled, the script only recognizes the current form). For the full argument see git log (git log --follow -- yzr-llm-wiki-management/SKILL.md, 0.31.0 commit).

  • Already solidified(all five subcommands satisfy both conditions): log append + truncate / index entry add/remove / touch updated+ clear reviewed stamp / new scaffolding (5 required frontmatter fields + H1, slug validation + refuse overwrite) / memory entry + index row.Leave as md: summary writing, whether to create entity/concept pages, contradiction handling, query synthesis and archiving consultation, semantic merging — all require reading content to make judgments
  • Escape hatch: manual writing is always valid, lint is the fallback — scripts are the default path, not a gate; if the agent encounters a form the script does not support, retreating to Edit/Write is not a violation
  • Scripts do not carry content knowledge: do not generate summaries, do not embed body templates (SSOT is in page-templates.md), do not do semantic merging — wanting to add "understanding" into a script is a signal that the boundary is being eroded
  • Single source of constants + version protection: wiki_write.py imports from lint_wiki.py / log_format.py (VALID_TYPES / LOG_RETENTION_LIMIT / LOG_LINE_RE, etc.), changing the spec's format does not increase change points; at startup, if the wiki §8 version is inconsistent with SKILL → warn "migrate first, then write" (non-blocking)

Four-layer architecture — why four layers

Referring to the core claim of the Karpathy gist:"Knowledge accumulation depends on discipline, not willpower". Each of the four layers bears one responsibility, and they check and balance one another:

  1. raw/ source of truth— the user is only responsible for curating raw materials, read-only for the LLM.Two write-permission exceptions： raw/external/(external code repository symlink integration, LLM-led, spec §13.3) + raw/discussions/ (collaborative draft layer, writable by both parties, spec §15). The full discipline (including the 4 rules such as "if wiki and raw conflict, raw prevails") is in <wiki-root>/AGENTS.md §1 (see the template in references/agents-md-template.md), operational details are in Core Principles §1 + spec §13/§15.raw/ subdirectories may be freely organized; ingest_diff.py recursively scans the entire raw/(extension whitelist .md/.markdown/*.txt; skip assets/ + discussions/）。
  2. wiki/ compounding asset——the LLM owns this layer (5 content page subdirectories + index.md). Humansdo not write wiki content, only read + ask questions. Every time new material is ingested or a new question is answered, the wiki becomesthickerrather than messier.
  3. MEMORY/ agent persistent memory (peer to wiki/ )——experience / pitfalls / user preferences accumulated by the LLM agent during work; users do not write it. Why put it in <wiki-root>/ rather than inside wiki/ : the physical location aligns with the logical layering (independent of wiki/ content), and when publishing in the future it is naturally kept as a private layer not shared externally.MEMORY.md is the single source of truth for the index (no frontmatter); AGENTS.md top @MEMORY/MEMORY.md loads it; changes are made only in this one place, with no copy drift. Operational details are in Core Principles §9 + Workflow §4 + spec §5.
  4. AGENTS.md discipline configuration (SSOT) + CLAUDE.md thin shell——concentrate the conventions for "how to write the wiki / what to write / what not to write" into AGENTS.md(tool-agnostic single source of truth), the "constitution" for the agent maintaining this wiki;CLAUDE.md is @AGENTS.md thin shell (yzr-multi-agent-context method: one set of sources, multi-agent compatible). Top @MEMORY/MEMORY.md + @scripts/SCRIPTS.md two lines @import closure + mandatory Read instruction as fallback (spec §5.1 + §14.3). Without it, the LLM degenerates into an ordinary chatbot; with it, the LLM is a "strictly disciplined wiki maintainer".

Four core operations——why four

ingest / query / lint / migrate each of the four operationsreciprocal payoff: ingest makes query more useful; query makes the wiki thicker; lint keeps ingest from piling up into a mess; migrate keeps a wiki running for 1-2 years from falling behind as the spec evolves.Running any one alone is a loss——this is the essence of "compounding". migrate differs from the other three ——it isperiodically triggeredrather than triggered on every wiki operation (it runs only when the spec version is upgraded), but without it an old wiki willrot at the format layerrather than the content layer, which is harder to notice. For the inputs / outputs of the four, see "Inputs / Outputs · Operation Artifacts".

Execution Principles / Boundaries

Core Principles

Operation preconditions (orient ritual, common to all operations): before each ingest / query / lint starts,does not depend on symlinks ——read the four-piece set in the following order before acting:

  1. Read <$LLM_WIKI_ROOT>/AGENTS.md——obtain this wiki's topic name, boundary configuration, Page Thresholds (the discipline SSOT is AGENTS.md；CLAUDE.md is @AGENTS.md thin shell, holds no discipline). AGENTS.md does not contain the tag whitelist (it is in wiki/tags.md——see this section §Core Principles §11). AGENTS.md top line @MEMORY/MEMORY.md + one line @scripts/SCRIPTS.md @import——automatically expands @import agents transparently get the full MEMORY / scripts text; for those that do not expand, the mandatory Read instruction at the top of AGENTS.md serves as fallback (see details in references/agents-md-template.md top).When elsewhere the skill reads AGENTS.md on demand also take the same @import link, noneed to separately Read MEMORY.md complete the index (unless you want to see each <slug>.md body).
  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 last ~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 scriptscomplete section contract(usage scenarios / calling conventions / role / prerequisites); not mandatory (a wiki may have no scripts/), butbefore triggering a non-standard workflowyou must first check (at the top of AGENTS.md the @scripts/SCRIPTS.md import has already loaded the full text, and the detailed contract is read out along with it)

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

  1. raw/ is controlled by the user, the LLM only reads(for the schema see <wiki-root>/AGENTS.md §1)——the LLM never writes/deletes/moves files under raw/ ; the user may add/update raw/ at any time (re-clipping, re-saving PDFs all count), and changes are re-digested by ingest (updating the corresponding source page body + updated，ingest_diff.py --check-stale mark items pending re-ingestion by mtime vs source updated ) two write-permission exceptions：

    • raw/external/ top level (flat layout) the LLM may lead the creation of symlinks + write anchor's [[entry]] block (see §1 batch ingestion of external code repo subsection + wiki-spec §13.3).raw/external/ files in the target repo ingested by aredivided by role: read-only during wiki maintenance operations (ingest / query / lint / migrate);development collaboration explicitly requested by the user(bug fixes / refactoring) does not count as a wiki operation and is not subject to the raw/ read-only constraint (the target is outside the repo and is fully at the user's disposal)——see wiki-spec §13.3
    • raw/discussions/ user + LLM both can writecollaborative draft layer (no frontmatter required / not entered into index / no log written;ingest_diff skipped,raw-modified lint excluded,sources: must not point to it); drafts are digested into the wiki by two paths (digest-style / converting to formal mv) both require user confirmation——see wiki-spec §15

  2. wiki/ is written by the LLM——the user never hand-writes wiki pages (except editing AGENTS.md, which is the schema)

  3. AGENTS.md is a schema, not documentation——it carries the wiki's discipline configuration, do not stuff content into it (for the complete discipline see agents-md-template.md §7 "The Discipline of This File Itself"). When writing new discipline, first determine its belonging: pass the three tests of presence / state / persona (wiki attributes; "doing wrong" is limited to illegal state / rot, writing-quality-type methods do not count) → write to the template; working methods / tools / routing → keep in this file——for the criterion SSOT see wiki-spec.md §2

  4. Every write must update log.md——appends always go through wiki_write.py log(format + full LOG_RETENTION_LIMIT Automatic truncation is guaranteed by the script, see §Design Decisions "Mechanical vs Judgment"); lint log-format / log-truncation-recommended only serves as a fallback for out-of-band manual edits

  5. Every page must carry YAML frontmatter—new pages go through wiki_write.py new(5 required (title / type / created / updated / tags) + recommended description（index.md entry summary comes from it) guaranteed by the script scaffolding; slug validation + overwrite refusal). Why these 5See wiki-spec.md §9(minimal intersection of OKF field completeness × lint consistency; fewer than 5 fields would make the "rot detection" judgment ineffective). Exceptions：

    • wiki/index.md = 6 keys required(5 required + okf_version）/ wiki/log.md = 5 keys required (both omit description）
    • MEMORY/MEMORY.md / wiki/tags.md = no frontmatter(index fragments + tag whitelist)
    • MEMORY/*.md = Only title required(the other 5 fields are all optional—MEMORY is the agent's private memory, frontmatter is optional decoration);type if extended to 7 types (5 content pages + memory / memory-entry）；tags ifnotgoes through wiki/tags.md whitelist;reviewed / reviewed_at not covered by lint fallback (MEMORY has no "manual review" semantic role) authoritative definition（type value / reserved rules / sources field specialization / credibility signals reviewed / contested / contradictions) see references/page-templates.md §1 —this clause is not copied again, lint thresholds are synchronized to that location.tags management see §Core Principles §11。

  6. Cross-references use relative paths——[link](sources/bigtable.md), not absolute paths, not wikilinks

  7. index.md is the single entry point for wiki content pages—all pages that are not log / not MEMORY must appear in wiki/index.md appears in

  8. A good answer to a query must ask "should this be archived"—what can be written back to the wiki should not be wasted in chat

  9. MEMORY/ is the LLM agent's private memory—proactively append when hitting pitfalls, discovering user preferences, or cross-ingest associations;new entries go through wiki_write.py memory add(frontmatter only requires title required + atomic append MEMORY.md index line,memory-not-indexed immune during creation);not mandatorily listed in index.md. MEMORY accumulation only modifies MEMORY.md this one copy, no copy drift. Write flow see Workflow §4.

  10. LLM modifying a reviewed page must clear the reviewed stamp—after each edit run wiki_write.py touch (automatically updated=now + delete reviewed / reviewed_at, see §Design Decisions "Mechanical vs Judgment"); lint_wiki.py use reviewed-stale as fallback. Complete lifecycle rules see agents-md-template.md §2 "Cognitive Quality Signals" (discipline canonical copy).

  11. tag whitelist is in wiki/tags.md(detailed wiki-spec.md §9.1)——LLM auto-extend bullet + user audit loop (delete bullet → next lint reports tag-not-in-taxonomy adjudicated by user);wiki/tags.md has no frontmatter, same form as MEMORY/MEMORY.md . Cross-spec upgrades go through lint_wiki.py --check-version --apply。 agents-md-template.mdThe "Tag Taxonomy" section carries the same rule (the canonical discipline copy = the template; the wiki-side AGENTS.md is rendered from it).

  12. This wiki's self-maintained scripts live under <wiki-root>/scripts/ + SCRIPTS.md index(see wiki-spec.md §14）——SCRIPTS.md Single-section form: each script starts with a - `<name>` — <一句话用途> one-liner + ### <name> — <label> The subsection contains the 4-element contract (usage scenario / invocation convention / effect / optional prerequisites). Top of AGENTS.md @scripts/SCRIPTS.md @import automatically loads the full text—the agent mustfirst look at that index line to know which scripts exist, then as needed Read scripts/SCRIPTS.md to fetch the full contract (@import is visible once expanded), and execute explicitly per the "invocation convention", does notautomatically traverse scripts/; to change a script, only change SCRIPTS.md this one copy.scripts/ does not follow the §9 5-required-fields rule, does not participate in lint_wiki.py scanning, and does not copy scripts bundled with skills (risk of version drift). agents-md-template.mdThe "scripts/ — this wiki repo's self-maintained scripts directory" section carries the same rule (canonical copy = template).

  13. yzr personal working habits——canonical copy = agents-md-template.md §9(the single maintenance point for the discipline body text; the habit list is governed by that section and is not enumerated here—to add or change habits, only change the template, do not touch this file, do not bump wiki_spec_version, old wikis are independently detected by agents-md-template-sync byte comparison and then re-rendered). A session that triggers this skill should first Read that section once before outputting to the user—these habits apply to all user-facing output.

Boundaries

  • Do notedit raw/ any file under — LLM is read-only (two write-permission exceptions:raw/external/ symlink integration + raw/discussions/ collaborative drafts; for complete rules see Core Principles §1 + spec §13.3/§15,must not extrapolateto other subtrees such as papers / articles / clippings—see spec §15.4 for the slippery-slope defense line)
  • Do notdelete wiki/ pages under — use archived: true marking + remove from index; to truly delete, delete the file directly (when git is enabled use git rm, when not enabled use plain rm）
  • Do notbypass AGENTS.md to invent conventions—if AGENTS.md does not say it,ask the user firstthen write
  • Do notsecretly archive during query—you must first present the answer + ask the user
  • Do notignore lint reports—a wiki not linted for a long time will inevitably rot
  • Do notuse git operations to break raw/ immutability—git clean / git checkout -- raw/ applies only when git is enabled; when git is not enabled there is no concept of "uncommitted changes" (lint automatically skips this item)
  • Do notuse tools other than Read to make "automatic" modifications to files in the wiki—all modifications go through Edit / Write and follow schema conventions
  • Do notignore the scripts/SCRIPTS.md index and directly traverse scripts/ to run scripts—you must first Read index to locate the tool
    • execute per the invocation convention in the section (see Core Principles §12 for details)

Anti-patterns (absolutely forbidden)

  • Hand-writing prose-style summaries like "write a paragraph first, then paste images" in wiki pages (the root cause of shotgun-scattered conflicting statements)
  • Scattering the same concept across multiple entities/ files (you must first search whether a page with the same name already exists)
  • Finishing after editing the wiki without appending a log entry — losing the operational semantic record (the right way:wiki_write.py log, see Core Principles §4)
  • Cross-wiki mutual references without updating the counterpart index (keeping the two wikis in sync is the user's responsibility)
  • Using Obsidian-only syntax ([[wikilink]]、![[embed]]) — this skill assumes generic Markdown
  • Copying the scripts bundled with the yzr-llm-wiki-management skill (lint_wiki.py / ingest_diff.py / log_format.py / wiki_write.py / check_wiki_fixtures.py) into <wiki-root>/scripts/— the SSOT is in the skill repo; this wiki's self-maintained scripts must also update SCRIPTS.md index section
  • Onboarding an external code repo via cp -r embedded into raw/ instead of raw/external/ symlink — losing the commit anchor + taking up space + violating spec §13 discipline
  • Modifying the anchor's remote_url / commit / branch three fields — these three fields are onboarding intent, not machine state (see references/external-repo-rebuild.md）
  • Bypassing the anchor and directly ln -s— no corresponding [[entry]] symlink = lint reports external-anchor-orphan
  • Under raw/external/ creating a <source-name>/ subdirectory — flat layout, all symlinks go directly in external/; violating subdirectories will be reported by lint as external-source-name-invalid
  • Extrapolating the writability of raw/discussions/ or raw/external/ targetsextrapolatingto other raw/ subtrees — "discussions/ can be modified, so papers/ can be modified too" / "target can be modified, so raw/ can be modified too" is a typical slippery slope (discussions/ + external/ arethe onlytwo exceptions; all other raw/ subtrees are read-only for the LLM; see wiki-spec §15.4 for the line of defense)
  • Making a type: source page's sources: point to raw/discussions/— drafts are not the source of truth, lint reports source-in-discussions(error); to cite it, first go through wiki-spec §15.3 to convert it to formal
  • Using raw/discussions/ to circumvent ingest discipline — stuffing draft content into a wiki page without going through log / index / clearing the reviewed stamp, i.e., bypassing the §15.3 provenance constraint

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

This skill contains 14+ lines of "must / forbidden / do not" + "do not" opening paragraphs = discipline-type. Discipline-type prohibitions will be circumvented under LLM pressure with various rationalization excuses — the trio only blocks one category:already-rationalized violations. Unrationalized violations (directly ignoring the rules) = missing the §Anti-patterns checklist itself, unrelated to the trio.

Rationalization Table

Baseline actual-run record (2026-08-16, 0.33.0 audit): 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 real excuse (row 1 of the table below) + one silent omission (frontmatter missing the required tags field, omitted directly with no excuse).

Common excuses Why it is wrong What should be done instead
"The clipping has only one sentence; per the 'restrained page creation' principle and the small matter you mentioned, handle it lightly — one resource page is enough" (2026-08-16 actual-run transcript) The user's "whatever / in a hurry" is an attitude, not an exemption — writing a wiki page triggers the 5 required fields / page-creation threshold / log discipline; "handle it lightly" uses the user's mood as a shield to skip discipline (in the same round a required tags field was also silently missed) The process is not cut down; the "restrained page creation" judgment is executed faithfully, butexplain to the user("This article has only one central topic; no concept page for now, add one when a second article on the same topic appears"), while field and log discipline proceed as usual
"The user didn't explicitly say to do this step" This skill's discipline points (log / lint / reviewed stamp / etc.) have trigger conditions based onthe eventrather thanthe person— writing a wiki page triggers lint, writing a source clears the reviewed stamp — the user not saying so = silence ≠ exemption First follow the §execution principles to complete discipline, then decide whether to omit; if omitting, state the reason clearly in the log entry
"This is a single-page ingest; skipping entity/concept sync is faster" Knowledge islands = wiki compound-interest deficit — a single page also needs cross-links; "faster" puts the current case above the compound-interest structure Even if only 1 entity page is linked, it must be synced; cross-referencing is the ROI core of the wiki
"I'll put the source cp into raw/ rather than going through Write + creating a page — more direct" raw/ is immutable + the raw/external/ exception is a symlink not a cp —cp into raw/ triggers raw-external-anchor-mismatch a whole chain of findings Use Edit/Write to write wiki/sources/<slug>.md; raw is the user's private
"reviewed: true was marked a week ago; I haven't changed much content, leaving it is fine" reviewed: true is a "content endorsement at this moment" snapshot;any LLM modification to the body invalidates it (including typos / field completion) — keeping the stamp = pretending it was reviewed After any Edit/Writemustdelete the reviewed + reviewed_at two fields, returning to the default unreviewed state
"Copying an external code repo with cp -r into raw/ also counts as onboarding; symlink is unnecessary" cp -r loses the commit anchor + occupies wiki repo disk + violates spec §13 — "also counts" confuses "onboarding intent" with "onboarding means" Go through ln -s to create the symlink + write .symlink-anchor.toml the [[entry]] block
"This wiki has no git, so not writing a log is fine" log.md recordsoperation semantics(ingest/query/lint) + a recent-activity overview (the orient ritual reads it to avoid repeated work) — this is what git diff does not directly reflect; only complete file history relies on git Any wiki changemustappend a log entry (even if the wiki has no git)

There are two types of entries in the table: line 1 = verbatim excerpt of the actual-run transcript; the other 6 entries = inferred from §anti-patterns / §boundariessuspect list(Multiple baseline attempts not reproduced) — keep as a candidate for future live-run verification / replacement. Maintain the principle of "only include what the agent actually said": replace upon live-run reproduction / do not add if not reproduced (pre-writing = noise + signal interference).

Violating the letter = violating the spirit

Any "looks different but has the same effect" workaround of the three sections of prohibitions in §Core Principles / §Boundaries / §Anti-Patterns counts as a violation — the top three common workarounds in this skill:

  • Changing Edit / Write to Read + manually generating new content then Write——does not countCircumventing the "use tools other than Read to make automatic modifications" prohibition; the tool operated is Write, so it counts the same
  • Interpreting "do not delete wiki pages" as "first copy the content out, then rm then write it back"——does not countCircumventing 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/ then immediatelyrm, within the window I read the content = equivalent to read-only"——does not count, the write happens in the first step

Prohibitedto use "strictly by the letter / strictly by the spirit" either-or wording to leave the agent a way out — any "looks different but is equivalent in effect" is a violation.

Red Flags (thought checklist — stop upon appearance)

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

  • "The user said 'just jot it down casually / in a hurry / don't be too formal' — so discipline can be relaxed" (2026-08-16 live-run observation)
  • "I think this step is unnecessary for the current case"
  • "The user didn't explicitly say to do this step"
  • "This is faster / saves more tokens / more efficient"
  • "The spec doesn't prohibit it"
  • "I've already done the equivalent thing" / "Same effect, doesn't count as a violation"
  • "Leave it like this for now, come back and fill it in later"
  • "Generating fields myself is more flexible than strictly writing frontmatter"
  • "Skip the log entry this time, it's a wiki not git anyway"
  • "The user changes 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, only by continuing further does it becomeaction. 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 stage(ingest / query / lint). The wiki repo'screation and deletionis handled by the external workspace CLI — for CLI command names and parameters see the CLI repo's documentation; this skill does not hard-bind to any CLI implementation. For the wiki repo's "birth form" contract see references/wiki-spec.md—— the interface between the CLI implementation and the SKILL.

Basic flow：

# 1. 调 workspace CLI 创建 wiki 仓（具体命令以 CLI 文档为准）
workspace wiki init "LLM Systems"
# CLI 按 wiki-spec.md 落盘：目录结构 + AGENTS.md（SSOT）+ CLAUDE.md（薄壳）+
# wiki/index.md + wiki/log.md + .gitignore + scripts/SCRIPTS.md +
# git 默认跳过（用户 --git opt-in 时才 init）。完整产物清单见 wiki-spec.md §1-§7。

# 2. 把原始资料放进 raw/（用户手动 / Obsidian Web Clipper / 浏览器下载）
cp ~/Downloads/some-article.md ~/wiki/<topic-name>/raw/articles/

What the LLM agent does after taking over：

  1. Verify CLI persistence——read <wiki-root>/AGENTS.md to confirm the topic name + date replacement 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 blockquote at the top of §Execution Principles / Boundaries)
  3. Ask the user whether to do the first ingest — if so, give the agent the path to the first material

Why setup and daily work are split into two layers: CLI = birth/death (one-time, structurally stable), LLM = growth (high-frequency interaction). The biggest benefit is decoupling of the wiki schema from the LLM workflow— the CLI can be upgraded independently (Python → Rust), while the SKILL stays unchanged.

1. Ingest (ingesting new material)

Trigger: "ingest this into the wiki" / raw/ there is a new file / run ingest_diff.py to find un-ingested items.

Workflow summary(agent-driven; for the detailed 7 steps + batch processing see references/ingest-workflow.md; for the 5-step integration of external code repositories / drift refresh / cross-host rebuild see wiki-spec §13.3 and references/external-repo-rebuild.md）：

  1. Run scripts/ingest_diff.py <wiki-root>(add --check-stalefor daily use) to find the list of un-ingested/to-be-re-ingested files
  2. briefly go over the key points for a single article— only for interactive single-article or small-batch scenarios: confirm the topic direction / the entities to cross-reference / what the user judges should be kept
  3. For each file: Read the full text → extract metadata → wiki_write.py new --type source ... create the skeleton → write the body (use Edit,for stale-raw, do not overwrite with Write) → sync entity/concept (only append the "Sources" section) → wiki_write.py index add → wiki_write.py log --op ingest → run wiki_write.py touch
  4. commiton edited pages (only when git is enabled): the cadence is decided by the user/agent,do notauto-commit

Batch ingestion (ingesting ≥ 3 raw files at the same time)

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

External code repositories as corpus— if the user says "bring repository X into the wiki":do notembed-copy the repository, go through wiki-spec §13 's symlink path (raw/ one of the write-permission exceptions to theoverall discipline— LLM-led integration; the other exception is raw/discussions/ collaborative drafts, see wiki-spec §15). 5-step integration (confirm symlink/target → LLM verification → read git extended fields → create symlink + write anchor → subsequent ingest_diff scans) + drift refresh + cross-host rebuild, see references/external-repo-rebuild.md。

2. Query (cross-page synthesis)

Trigger: "does the wiki have X" / "summarize what the wiki says about Y" / "compare A and B".

Workflow：

  1. Look at index.md first— 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— cite sources in reference form; explicitly flag contradictions: "A says X (source: ...), B says Y (source: ...), needs deeper investigation"
  4. Present the answer + ask about archiving— if the answer is of a "comparison / synthesis / connection found" nature, ask the user: "Is this answer suitable for archiving back into the wiki as comparisons/<slug>.md?"
  5. Archive after user consent—follow references/page-templates.md's comparison or synthesis template + append log entry

For the detailed query flow 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.

Flow：

  1. Run scripts/lint_wiki.py <wiki-root> to do deterministic checks
  2. script coverage (major categories below, for the 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 trustworthiness signals (reviewed / contested / contradictions）/ raw/external/ symlink ↔ anchor association (spec §13) / fixtures consistency (see the "fixtures consistency check" section below)
  3. After the script output, 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 LLM agent persistent memory)

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

When to write：

  • Encounter a pitfall (e.g., raw/ PDFs frequently have OCR errors; next time have the user convert the format first)
  • Discover a user preference (e.g., the user prefers tabular comparisons and dislikes prose-style summaries)
  • Cross-ingest association (two source pages point to different chapters of the same paper)
  • Recurring pattern in lint reports (every lint reports some type missing a field)

Flow summary(agent-initiated; the authoritative definitions of frontmatter fields / index sync / full vs. short entry determination are in spec §5 + §5.2 + repository root MEMORY/MEMORY.md index's own conventions):

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

Discipline：

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

5. Migrate (upgrade wiki spec)

Trigger: the user says "upgrade wiki / migrate / check wiki version / old format / spec upgrade / whether reformat is needed"; or lint_wiki.py reports legacy-confidence-field and other migration-period warns.

Division of responsibilities(to avoid confusion with ingest / lint):

  • Script（scripts/lint_wiki.py --check-version，includesauto-invokes check_wiki_fixtures.py convention files) = detector, scans only without fixing, outputs a report / --apply when stdout outputs migration plan
  • agent = fixer, follows the migration plan returned on stdout (actions[] carries its own remove/add_or_modify/to_action) use Edit/Write to change frontmatter / move files / add index entries / sync AGENTS.md to the template (full re-render, wiki-spec §10.1); follow plan.fixtures_actions[] to fix convention files; semantic merge follows references/migrate-workflow.md §6 follows
  • during migration, do not follow wiki_write.py——migration = format flux period, mechanical write commands only recognize the current form (admission rules excepted, see §Design Decisions "Mechanical vs Judgment")
  • migration is based on SSOT = plan actions[] + migrate-workflow.md §6 (semantic merge)—— no separate historical archive is set up; fixtures-check semantic merge follows migrate-workflow.md §6 (separate from §3 byte compliance)
  • do notappend log entries (migration is a script run, not a wiki operation event)

fixtures consistency check——--check-version auto-invokes scripts/check_wiki_fixtures.py scans the wiki repo's 10 categories of convention files (AGENTS.md §8 / .gitignore / index.md / log.md / tags.md / MEMORY/MEMORY.md / MEMORY/*.md entries / SCRIPTS.md / .symlink-anchor.toml / wiki_metadata.toml), findings are merged into migration plan(stdout JSON output) of fixtures_actions[](parallel to legacy actions[] ). Number of check items is the same as metadata.fixtures_check_count(two categories: structural detection + skeleton field comparison, breakdown see references/lint-checklist.md; among them, agents-md-template-sync performs on the entire AGENTS.md text atemplate render byte comparison——if inconsistent, do full re-render + migrate local customizations to MEMORY/, see wiki-spec §10.1 for details).brief flow + detailed steps + field list see references/migrate-workflow.md。

reference examples

5 complete examples (setup / ingest / query / lint / migrate) see references/examples.md——Read on demand.