SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsllm-wiki-management

llm-wiki-management

Agents & models

View repository

Updated 10-16 08:01

About this skill

LLM Wiki Management

Per Karpathy LLM Wiki design philosophy maintain alocal、compound-accumulatingknowledge base: the user only reads + provides material + asks questions; the LLM handles the "boring parts" such as summaries, cross-references, archiving, and bookkeeping. And outline-wiki-upload The key difference from cloud skills such as is local files + three-layer discipline——vs the cloud MCP single-layer document.

This skill provides three deliverables:

  • SKILL.md (this document)——the "constitution" of workflow + discipline
  • scripts/——ingest_diff.py / lint_wiki.py / log_format.py + new in 0.18.0+ check_wiki_fixtures.py(fixtures consistency check;lint_wiki.py --check-version called automatically once), to lock down high-frequency deterministic tasks (notincluding setup_wiki——creation of the wiki repo is handled by the external workspace CLI)
  • references/——loaded on demand: AGENTS.md schema template + CLAUDE.md thin-shell template, detailed procedures for each operation, page templates, wiki-spec.md (CLI implementation contract), fixtures (gold standard for byte-level CLI comparison), lint-checklist §5 (semantic-merge rules, the merge basis when the agent follows .migration-plan.json)

When to use / not use

Use

  • The user says in conversation "ingest/archive to wiki / ingest to wiki / organize this article into the wiki"
  • The user says in conversation "is there X in the wiki / search the wiki / summarize what the wiki has about Y"
  • The user says in conversation "lint wiki / wiki health check / find contradictions / find orphan pages"
  • The user says in conversation "upgrade wiki / migrate to the latest spec / check wiki version / old format / reformat"—— follow §5 Migrate
  • The user points to <wiki-root>/raw/ newly appearing / unarchived files
  • The user first mentions "I want to set up a wiki to manage research / reading notes / projects for X"
  • The user mentions "how to write AGENTS.md / the boundary between raw/ and wiki/"
  • The user wants to include an external code repository (Linux kernel / Ray source, etc.) as corpus into the wiki——follow raw/external/ flat symlink + .symlink-anchor.toml paths (see wiki-spec §13）

Do not use

  • cloud collaborative wiki(Notion / Confluence / Outline Wiki / GitHub Wiki)——follow outline-wiki-upload(write / edit) / outline-wiki-search(search / read)
  • one-off document generation(not cumulative)——just use the ordinary file-writing workflow
  • no raw/ material + no cumulative need——the value of the skill is "compound interest"; one-off organizing does not need it
  • needs a strongly structured database(with schema / SQL / full-text search backend)——when the wiki scale is ≤ 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)

Input / Output

Information required at startup

Information Source Notes
Wiki root LLM_WIKI_ROOT environment variable, or asked interactively Example ~/wiki/llm-systems
Topic name Specified once at setup, written to AGENTS.md Example "LLM Systems"
Operation type User natural language ingest / query / lint / migrate / setup
Trigger material At ingest, give a file path or directory Must be within raw/ Inside

Operation artifacts

  • setup → Done by the external workspace CLI (persisted according to references/wiki-spec.md ), this skill does not implement the creation logic; the 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 entry + update index.md
  • query → Give an 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 output spec version + legacy status report;--apply persist <wiki-root>/.migration-plan.json for the agent to follow wiki-spec.md Appendix B to perform Edit/Write fixes; see §5 Migrate for details

Design decisions

Four-layer architecture—why four layers

Referencing the core argument of the Karpathy gist:"Knowledge accumulation depends on discipline, not willpower". Each of the four layers bears one responsibility, and they check and balance each other:

  1. raw/ Source of truth—the user is only responsible for curating raw materials (papers, clippings, PDFs, notes, podcast transcripts), read-only for the LLM.The only exception：raw/external/ top level (flat layout, 0.17.0+) the LLM maycreate symlinks + write .symlink-anchor.toml the [[entry]] block (first onboarding + drift refresh)—see wiki-spec §13.3
    • wiki-spec §13.5; the remaining raw/ subtrees (articles / papers / assets / clippings / podcasts, etc.) remain read-only for the LLM. Full definition of the discipline(including the 4 rules: the LLM does not write / the user may modify / renaming breaks links / when wiki and raw conflict, raw prevails) see <wiki-root>/AGENTS.md §1 (copied by the workspace CLI to each wiki at init, template see references/agents-md-template.md）。 raw/ subdirectories may be organized freely—the CLI creates by default articles/ + assets/, but podcasts/ / clippings/ / papers/ / external/ and other custom subdirectories are equally usable;ingest_diff.py recursively scans the entire raw/。
  2. wiki/ Compounding asset—the LLM owns this layer (5 content page subdirectories + index.md). Humansdo not write wiki content, only read + ask questions. Each time new material is ingested or a new question is answered, the wiki becomesthickerrather than messier.
  3. MEMORY/ agent persistent memory (peer to wiki/ )—the experience, pitfalls, and user preferences accumulated by the LLM agent during work, physically located at <wiki-root>/MEMORY/(peer to wiki/ , not nested in wiki/ below), shares the same ownership as wiki content pages (written by the LLM, not by the user) butdoes notfollow the single-entry constraint and is not scanned by lint as a wiki content page.MEMORY.md It is an index, used by AGENTS.md via @MEMORY/MEMORY.md import sessions that stay resident—avoiding MEMORY degenerating into a write-only, never-read dead store. Why move it to <wiki-root>/MEMORY/: corresponds to §Four-Layer Architecture Layer 3 (independent of wiki/ content), and in the future when publishing, MEMORY naturally remains as a private layer not shared externally. See spec §5 for detailed rules.
  4. AGENTS.md discipline configuration (SSOT) + CLAUDE.md thin shell—concentrates the conventions of "how to write the wiki / what to write / what not to write" into AGENTS.md(a tool-agnostic single source of truth), serving as the "constitution" for the agent maintaining this wiki.CLAUDE.md is a @AGENTS.md thin shell, only for Claude Code to read the SSOT via the auto-load convention; other agents that read AGENTS.md (Qoder / Codex / Gemini CLI, etc.) read it natively and directly. Without it, the LLM degenerates into an ordinary chatbot; with it, the LLM is a "strictly disciplined wiki maintainer".Why AGENTS.md as SSOT + CLAUDE.md thin shell(applying the yzr-multi-agent-context method): one source of truth, coexistence of dual tools like Claude Code / Qoder—@import written inside the SSOT, both sides can load it.

Four core operations—why four

Operation Input Output Value
ingest raw/ new file Summary page + cross-references + log entry Turn raw material into a queryable structure
query Natural language question Synthesized answer (with citations) + optional archiving Reuse + compounding: good answers don't go back into chat logs
lint The entire wiki Report contradictions / orphans / staleness Prevent the knowledge base from rotting
migrate The entire wiki (including AGENTS.md §8) legacy report + .migration-plan.json + the latest spec-compatible wiki after agent fixes Don't break the accumulated old wiki when the spec evolves

Every operationrewards both ways: ingest makes query more useful; query makes the wiki thicker; lint keeps ingest from piling up into a mess; migrate keeps a wiki that has run for 1-2 years from falling behind when 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 (only run when the spec version is upgraded), but without it the old wiki willrot at the format layerrather than the content layer, which is harder to notice.

Why not use the cloud

outline-wiki-upload / outline-wiki-search goes through cloud MCP (Outline Wiki), suitable for team collaboration, external sharing, and permission management. This skill goes throughlocal files(git is an optional opt-in), for these reasons:

  • Privacy—research / reading / personal thinking don't need to go to the cloud
  • Portability—pure Markdown + files, not tied to any platform
  • No external dependencies—no OAuth / API key / network needed
  • Version control optional—git (during setup --git enabled) provides history / diff; not enabling it does not affect ingest / query / lint (see wiki-spec.md §7）

Stance：wiki Works without relying on git—by default it is stored on disk as a pure directory tree; git is enabled only when, during setup, the user explicitly opts in (--git) .

The two sets of skills do not conflict: local research accumulation → cloud sharing; the direction is one-way.

Execution Principles / Boundaries

Core Principles

Pre-operation (orient ritual, common to all operations): before each ingest / query / lint starts,Does not rely on symlinks —read the four-piece set in the following order before acting:

  1. Read <$LLM_WIKI_ROOT>/AGENTS.md—get this wiki's topic name, boundary configuration, Page Thresholds (0.11.0+: the discipline SSOT is AGENTS.md；CLAUDE.md is @AGENTS.md a thin shell and does not hold discipline). AGENTS.md no longer contains the tag whitelist (moved out in 0.8.0+ to wiki/tags.md—see §Core Principles §11 in this section), butcontains @MEMORY/MEMORY.md + @scripts/SCRIPTS.md imports (since 0.9.0+, written in the SSOT). When working inside the wiki root directory—Claude Code automatically loads the SSOT (including the index) via the thin-shell CLAUDE.md → @AGENTS.md ; other agents that read AGENTS.md (Qoder / Codex / Gemini CLI, etc.) natively read the SSOT; elsewhere, when the skill reads AGENTS.md on demand, @ does notautomatically expand; additional Read <$LLM_WIKI_ROOT>/MEMORY/MEMORY.md + depending on the situation Read <$LLM_WIKI_ROOT>/scripts/SCRIPTS.md complete the index
  2. Read <$LLM_WIKI_ROOT>/wiki/index.md—know which pages exist and which categories they are distributed across, avoiding duplicate creation / missed cross-references
  3. Read <$LLM_WIKI_ROOT>/wiki/log.md(the most recent ~30 lines is enough)—see the recent activity clearly, avoiding duplicate ingest / missed archiving of old work
  4. 0.9.0+： Read <$LLM_WIKI_ROOT>/scripts/SCRIPTS.md—confirm whether this wiki has available project-level extension scripts (batch ingest / external CLI glue / automation hooks); if so, explicitly execute according to the "invocation conventions" in the section; not mandatory (a wiki may have no scripts/), butbefore triggering a non-standard workflowmust first check

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/ across the whole 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 is read-only(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 and re-saving a PDF both count); changes are re-digested by ingest (updating the corresponding source page body + updated，ingest_diff.py --check-stale marks items pending re-ingestion by mtime vs source updated ) The only exception：raw/external/ top level (flat layout, 0.17.0+) the LLM may lead the creation of symlinks + write anchor [[entry]] blocks (see §1.bulk external code repository subsection + wiki-spec §13.3)

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

  3. AGENTS.md is the schema, not documentation—it is a "work code" for the LLM to read; do not stuff content into it

  4. Every write must update log.md—the format is strict; the authoritative definition is in <wiki-root>/AGENTS.md §1 (for the regex see references/page-templates.md §7; the script uses scripts/lint_wiki.py shall prevail)

  5. Every page must have YAML frontmatter——5 required (title / type / created / updated / tags) + recommended description（index.md entry summaries come from it). Why these 5see wiki-spec.md §9(the minimal intersection of OKF field completeness × lint consistency; fewer than 5 fields makes the "rot detection" judgment ineffective). Exceptions：

    • wiki/index.md / wiki/log.md = 4 fields required(omit description）
    • MEMORY/MEMORY.md / wiki/tags.md = no frontmatter(index fragments + tag whitelist)
    • MEMORY/*.md（0.19.0+）= 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 categories (5 content pages + memory / memory-entry）；tags If takingnotgo through the wiki/tags.md whitelist;reviewed / reviewed_at does not go into lint fallback (MEMORY has no "human 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 does not re-copy, lint thresholds are synchronously governed by that location.tags is managed in §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 appear in

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

  9. MEMORY/ is the LLM agent's private memory——when hitting pitfalls, discovering user preferences, or cross-ingest associations, proactively append; frontmatter only title required(the other 5 fields are all optional, decoupled from the 5-required rule for wiki content pages ——spec §5.2),not mandatorily listed in index.md，but each one must be listed in a row in the MEMORY/MEMORY.md index(that index is imported by AGENTS.md @ so it persists in the session, otherwise next time it cannot be read). See spec §5 + wiki-spec.md

  10. LLM modifications to reviewed pages must clear the reviewed stamp——any LLM modification to the page body (ingest re-ingestion / query archiving / refine / any Edit/Write) invalidates the stamp;must delete reviewed + reviewed_at two fields return to the default unreviewed state, to be re-reviewed by a human.lint_wiki.py uses reviewed-stale（reviewed: true exists and updated > reviewed_at) as fallback. SSOT:page-templates.md §1。

    Note: the same rule also appears in references/agents-md-template.md §2 "Cognitive Quality Signals" final paragraph——there the wiki's built-in AGENTS.md template must be self-contained (cross-repo references to SKILL.md cannot be resolved); the wording in both places is deliberately kept consistent. The SSOT is page-templates.md §1.

  11. The tag whitelist is in wiki/tags.md(from 0.8.0+ onward, see wiki-spec.md §9.1)——LLM auto-extend bullet + user audit loop (delete bullet → next lint reports tag-not-in-taxonomy decided 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 is self-contained with the same rule (mandatory — the wiki repo's own template cannot reference SKILL.md across repos).

  12. This wiki's self-maintained scripts go through <wiki-root>/scripts/ + SCRIPTS.md index(since 0.9.0+, see wiki-spec.md §14）——SCRIPTS.md by the wiki repo AGENTS.md with @scripts/SCRIPTS.md import kept resident in session; agent mustfirst Read SCRIPTS.md locate the section, then explicitly execute per the "invocation convention",notautomatically traverse scripts/; script and index section modifications are atomic actions。scripts/ not subject to §9 5 required fields, do not participate in lint_wiki.py scanning, do not copy skill-bundled scripts (version drift risk).agents-md-template.mdthe "Wiki-local scripts" section is self-contained with the same rule.

Boundaries

  • Do notedit raw/ any file under it — LLM is read-only; users may modify, and after modification ingest re-digests sole exception：raw/external/ top level (flat layout, 0.17.0+) LLM may create symlink + write .symlink-anchor.toml 's [[entry]] block (first onboarding + drift refresh; spec §13.3)
  • Do notdelete wiki/ pages under it — 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,ask the user firstthen write
  • Do notsecretly archive during query — must first present the answer + ask the user
  • Do notignore lint reports — a wiki not linted for a long time will definitely rot
  • Do notuse git operations to break raw/ immutability —git clean / git checkout -- raw/ only applies 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 notretain the reviewed: true stamp after LLM modifies a page — the stamp is expired, return to default unreviewed (see core principles §10)
  • Do notignore scripts/SCRIPTS.md index and directly traverse scripts/ to run scripts — must first Read index to locate the tool
    • execute per the section's invocation convention (see core principles §12)

Anti-patterns (absolutely prohibited)

  • writing prose-style summaries like "first write a paragraph then paste an image" by hand in wiki pages (the root of scattered shotgun-style conflicting conventions)
  • scattering the same concept across multiple entities/ files (must first search whether a page with the same name already exists)
  • modifying the wiki without writing a log entry (cannot audit + cannot ingest_diff to identify new files)
  • Cross-wiki mutual references without updating the other side's index (keeping the two wikis in sync is the user's responsibility)
  • Using Obsidian-only syntax ([[wikilink]]、![[embed]]) — this skill assumes generic Markdown
  • Copy the scripts bundled with the llm-wiki-management skill (lint_wiki.py / ingest_diff.py / log_format.py) into <wiki-root>/scripts/— the SSOT is in the skill repo; this wiki's self-maintained scripts must also update the SCRIPTS.md index section
  • Connecting an external code repo goes through cp -r embedded into raw/ rather than raw/external/ symlink — losing the commit anchor + taking up space + violating spec §13 discipline

Workflow / Steps

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

Responsibility boundaries: this skill is only responsible for the wiki'sgrowth phase(ingest / query / lint). The wiki repo'screation and deletionare handled by the external workspace CLI — for CLI command names and arguments, 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（0.9.0+）+
# 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 the CLI wrote to disk — read <wiki-root>/AGENTS.md to confirm the topic name + date were substituted correctly; wiki/index.md / wiki/log.md exists and the frontmatter is complete;<wiki-root>/CLAUDE.md is a thin shell
  2. Run the orient ritual (see the blockquote referenced at the top of §Execution Principles / Boundaries)
  3. Ask the user whether to do a first ingest — if so, give the agent the path to the first material

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

1. Ingest (ingest new material)

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

Process summary(agent-driven; for the detailed 7 steps + batch processing + external code repo 5 steps, see references/ingest-workflow.md）：

  1. Run scripts/ingest_diff.py <wiki-root>(for daily use add --check-stale) to find the list of un-ingested/to-be-re-ingested files
  2. Check the key points for a single item— only for interactive single-item or small-volume scenarios: confirm the topic direction / entities with key overlaps / what the user judges should be kept
  3. For each file: Read the full text → extract metadata → write wiki/sources/<slug>.md(for stale-raw go through Edit,do notWrite overwrite) → sync entity/concept (only append the "Sources" section) → update wiki/index.md → append log.md
  4. commit(only when git is enabled): the pace is decided by the user/agent,do notauto-commit

1.bulk Batch ingest (ingesting ≥ 3 raw files at the same time)

Go through 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 batch processing + the details of the log title prefix Bulk: , see references/ingest-workflow.mdthe "Batch Processing" section.

External code repos as corpus—If the user says "bring repo X into the wiki":Nono inline repo copy; go via wiki-spec §13 symlink path (raw/ the general discipline'sonly exception—LLM-led). 5-step onboarding (confirm symlink/target → LLM validation → read git extension 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: "is there X in the wiki" / "summarize the wiki's content on Y" / "compare A and B".

Flow：

  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—cite with source links; explicitly mark 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 / discovered connection" nature, ask the user: "Is this answer suitable for archiving back into the wiki as comparisons/<slug>.md?"
  5. After user agreement, archive—go through references/page-templates.md's comparison or synthesis template + append a log entry

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

3. Lint (health check)

Trigger: "lint wiki" / periodic (frequency thresholds see lint-checklist.md §6) / proactively suggested for large wikis.

Flow：

  1. Run scripts/lint_wiki.py <wiki-root> for deterministic checks
  2. Script coverage (10 major categories, details 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 (spec §13) / fixtures consistency (0.18.0+, see §0.18.0+ section)
  3. After the script outputs, the agent must also do semi-qualitative checks: contradictory claims / missing cross-references / suggest new ingestion directions
  4. Report + ask the user which to fix

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

4. Memory (write persistent memory for the LLM agent)

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

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 connection (two source pages point to different chapters of the same paper)
  • Recurring pattern in lint reports (every lint reports some type as missing a field)

Flow summary(agent-led; the complete 8 steps + frontmatter fields + index sync rules + full/short entry determination see references/migrate-workflow.md MEMORY section—this file contains MEMORY writing details; or the repo root MEMORY/MEMORY.md index's own format):

  1. Decide whether it is worth writing—can it make future agent work smoother?
  2. Determine entry form:full(with why+how context) → go to 3-6;short(pure reminder) → skip directly to 5
  3. In MEMORY/<slug>.md create the file (kebab-case categorized by topic,notarchived by time)
  4. write frontmatter (only title required; the other 5 fields are all optional—spec §5.2; short entries may have just 1 line title:）
  5. write the body—record the concrete experience, including context / resolution steps / how to avoid it in the future
  6. append in sync MEMORY/MEMORY.md one index line (omitting it = unreadable next time, lint memory-not-indexed as a fallback）
  7. do notappend a log entry / do notlist it in wiki/index.md (MEMORY does not follow the single-entry constraint)

Discipline：

  • Do not delete any MEMORY file—pitfall records accumulate
  • when writing a new file, keep the original created field; only update updated
  • Usermust notdirectly edit MEMORY/—if the user wants to add something, first tell the agent and let 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，includesautomatically call 0.18.0+ check_wiki_fixtures.py scan convention files) = detector, scans only and does not fix, outputs a report / writes to disk .migration-plan.json
  • agent = fixer, according to .migration-plan.json + wiki-spec.md Appendix B uses Edit/Write to modify frontmatter / move files / supplement the index / modify AGENTS.md §8; goes through plan.fixtures_actions[] to fix convention files; semantic merging follows references/lint-checklist.md §5 follows
  • wiki-spec.md Appendix B = SSOT (the basis for migration is written line by line over there); fixtures-check semantic merging follows lint-checklist §5 (separate from §3 byte compliance)
  • do notappend a log entry (migration is a script run, not a wiki operation event)

0.18.0+ new capability: fixtures consistency check (0.20.0+ upgraded to field-level skeleton comparison)

--check-version automatically calls scripts/check_wiki_fixtures.py scans the wiki repo's 9 types of convention files, finding is merged into .migration-plan.json 's fixtures_actions[](parallel to legacy actions[] ). metadata.fixtures_check_count checks—11 structural probes + 7 0.20.0+ skeleton field comparisons; skeleton check reads references/canonical/ + references/fixtures/gitignore.txt as SSOT (changing fixtures → check follows automatically), pure skeleton files compare all fields, growing files compare only required structure,does not touch growing content. For the field list (what each convention file aligns with during upgrade), see references/migrate-workflow.mdthe "fixtures field update list" section.

Brief process(agent-driven; for the detailed 8 steps + boundaries + coordination with lint, see references/migrate-workflow.md）：

  1. orient ritual（AGENTS.md + wiki/index.md + wiki/log.md the most recent ~30 lines)
  2. run scripts/lint_wiki.py "$LLM_WIKI_ROOT" --check-version——dry-run report + legacy pattern grouping + conflict pages highlighted in red + fixtures-check section (each failed item includes expected/actual); also can separately scripts/check_wiki_fixtures.py <wiki-root> [--json] run the convention file scan
  3. ask the user "apply all / partial / view list only"
  4. User agrees → scripts/lint_wiki.py ... --check-version --apply write to disk .migration-plan.json (including legacy actions[] + fixtures fixtures_actions[], if it already exists, refuse to overwrite)
  5. agent fixes in order: first fixtures_actions[](convention file) → then actions[](content page frontmatter) → skip skipped_conflicts[](never automatically overwrite human decisions); semantic merging follows lint-checklist §5
  6. Edit changes <wiki-root>/AGENTS.md §8 "Wiki Spec Version" to to_version
  7. rerun lint_wiki.py --check-version to verify;needs_migration == false is complete
  8. clean up temporary files: delete <wiki-root>/.migration-plan.json + the *.bakproduced by the upgrade (keep the wiki clean; see references/migrate-workflow.md step 8）
  9. do notappend a log entry / do nottrigger ingest / query / lint

complete examples：references/examples.md §5 ("check whether the wiki needs upgrading to the latest spec").

reference examples

5 complete examples (setup / ingest / query / lint / migrate) are moved down to references/examples.md——Read on demand.

Relationship to OKF (Open Knowledge Format)

This skill's output (wiki/ markdown + YAML frontmatter + index.md/log.md) deliberately stays close to OKF v0.1—— the knowledge format of "markdown + frontmatter, readable by both humans / agents". It is OKF'spractical subset, not verbatim compliance.

Aligned：

  • Each concept page has parseable YAML frontmatter (OKF §9 ①)
  • Each page's frontmatter contains a non-empty type（OKF §9 ②）
  • adopts the OKF recommended field description——index.md entry summaries come from it; do not hand-write a second copy in index (OKF §4.1)
  • bundle root index.md declares okf_version: "0.1"（OKF §11）

Known divergences (intentionally kept)——the local single-user wiki prioritizes "catch rot + grep-friendly", rather than cross-tool interchange:

Dimension This skill OKF v0.1 Reason for keeping
index.md/log.md with frontmatter Yes §6 index has no frontmatter convenient for local parsing / grep
log.md entries ## [date] op | title single line §7 ## date + * **Update** list keep the op dimension,grep "^## \[" can be used
Cross-links relative ../concepts/x.md §5 recommends bundle absolute /concepts/x.md all skill / lint parsing is built on relative paths; migration cost is high
Broken links lint reports error §5.3 consumers must tolerate broken links actively catching rot on the production side is the value of lint
type value fixed 5 categories 1 §4.1 open (producer-defined) a subset of the OKF open set

This wiki can be "best-effort read" by any OKF consumer (the tolerant consumption model in §9 requires that it must not be rejected due to the above discrepancies), but it does not claim 100% compliance. When exchanging bundles across organizations, converge to the "fully compliant" tier (remove index/log frontmatter, change log to ## date + list, change relative links to bundle-absolute).

Boundaries with other skills

Skill Scenario Medium
This skill (llm-wiki-management) Personal / research local compounding knowledge base Local Markdown (git optional opt-in)
outline-wiki-upload Team / collaboration: write / edit / push diagrams to Outline Outline Wiki MCP
outline-wiki-search Team / collaboration: search / read Outline documents Outline Wiki MCP
design-doc-edit Single design document writing (including mandatory section skeleton) Single-file Markdown
gemini-paper-summary Structured summary of a single paper (including visual figure extraction) Single-file Markdown + images

Serializable:gemini-paper-summary figure extraction → this skill ingest archive to wiki → (future independent publish skill) → outline-wiki-upload share externally

Paper domain: local workflow for paper-topic wikis

This skill never pushes to remote. This section only specifieslocalpaper-domain conventions; publishing papers to the cloud / Outline goes througha future independent publish skill(decoupled from this skill; cross-skill orchestration glue is not this skill's responsibility).

Trigger conditions: the user wants to accumulate a batch of papers into a local wiki—gemini-paper-summary PDF extraction is upstream, and this skill does archiving + multi-round distillation; temporary paper reading that does not want to enter the wiki does not apply to this section.

Authoritative definition：references/paper-wiki-profile.md— including raw identity (gemini "full extraction", not PDF / not compressed summary), source page lifecycle (quick draft → mature through multiple rounds of refine), new refine log op, and gemini-paper-summary responsibility split, and several anti-patterns.This section does not recopy—the profile is the SSOT; when the profile changes, SKILL.md just needs to synchronously reference the link.

Why it is a separate profile and does not pollute the general SKILL.md: the paper domain's "raw = full extraction (expensive to read once, repeatedly squeeze the text layer)" is Karpathy's "compounding" replayed inside a single paper, and should not be tied to general wiki rules; the profile makes variants on top of the general rules, and the SSOT remains clean.

Footnotes

  1. The 5 categories refer to entity / concept / source / comparison / synthesis; there are also 2 reserved categories (type: index / type: log) used only as file markers, see wiki-spec.md §8。 ↩