wiki-lint
Use when auditing a wiki for health issues — contradictions between pages, orphan pages, broken cross-references, stale claims, missing pages, or coverage gaps. Run after every 5-10 ingests.
kfchou · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add kfchou/wiki-skills --skill wiki-lintAbout this skill
name: wiki-lint description: Use when auditing a wiki for health issues — contradictions between pages, orphan pages, broken cross-references, stale claims, missing pages, or coverage gaps. Run after every 5-10 ingests.
Wiki Lint
Audit the wiki as a four-phase pipeline that keeps page bodies out of the main context: a deterministic script (Phase 1) and per-cluster subagents (Phase 2) do the heavy reading; the main thread only assembles findings. Produce a categorized report, offer concrete fixes, log the operation.
Pre-condition
Find SCHEMA.md (search from cwd upward, or ~/wikis/). If not found, tell the user to run wiki-init first. Read it to get wiki root path and conventions.
Link style. Read link_style: from SCHEMA.md. If the field is missing or <wiki-root>/config/link-style.md does not exist, default to obsidian ([[slug]]). Otherwise, read <wiki-root>/config/link-style.md. All link scanning below uses the ## Parse rule from that file (which may match more than one form). The lint report you write is itself a wiki page, so its cross-references use the ## Emit rule.
Why the pipeline
The old whole-wiki pass loaded every page body into one context — it nuked the context window as the wiki grew. Instead:
- Phase 1 runs
bin/lint-mechanical.py, which computes the deterministic checks (graph and string properties) with no LLM and no bodies in your context, and emits the tag-cluster list for Phase 2. - Phase 2 dispatches one subagent per tag cluster. Each reads only its cluster's pages (bodies live in the subagent's context, discarded on return) and reports the cross-page and body-level findings. You aggregate compact findings, never bodies.
Phase 1 checks are whole-wiki exhaustive. Phase 2 checks are cluster-scoped: a page that shares no tag with any other page is not body-checked (approach A's accepted recall limit — see Phase 2). Run lint periodically (every 5–10 ingests) so the scoped passes accumulate coverage.
Process
Phase 0 — regenerate the index
python bin/generate-index.py so the index reflects current page frontmatter.
Phase 1 — deterministic checks (script, no LLM)
Run python bin/lint-mechanical.py and parse its JSON. It returns:
{ "findings": { "broken_links": [...], "missing_frontmatter": [...], "orphans": [...],
"slug_collisions": [...], "stale_date": [...], "missing_concept": [...] },
"clusters": [ {"pages": ["slug-a", "slug-b"], "split": false}, ... ] }
These map to report sections directly:
- 🔴 Broken links —
broken_links({page, link}). - 🔴 Missing frontmatter —
missing_frontmatter({page, missing:[...]}).overview.mdlives inwiki/, notwiki/pages/, and is exempt. - 🟡 Orphan pages —
orphans({page}): zero inbound[[slug]]links. - 🟡 Colliding slugs —
slug_collisions({token, pages:[...]}): a bare slug clashing with qualified ones (mercuryvsmercury-element). Flag the pair; never auto-rename — renaming is awiki-mergesplit. - 🟡 Stale claims —
stale_date({page}): not updated in 90 days and the body still sayscurrent/latest/recent/state-of-the-artor names a year ≥2 years old. - 🔵 Missing concept pages —
missing_concept({slug, count}): a[[slug]]referenced 3+ times with no page.
Do not re-derive these by reading pages yourself — the script is the source of truth.
Phase 2 — cluster subagents (contradictions + body-level checks)
For each cluster in the Phase 1 clusters list, dispatch a subagent (parallel fan-out,
batched to bound concurrency). Give it the cluster's page paths and this instruction:
Read these pages. Report, within these pages only, as a compact list — each finding as
{type, pages:[slug,...], detail}, orcleanif none:
contradiction— two pages describe the same entity with conflicting dates, counts, names, or relationships.missing-xref— two pages clearly discuss the same entity but don't[[link]]each other.merge-candidate— two pages describe the same concept under different slugs (near-duplicate titles / near-identical Description sections).chronological-section— a page body carries date-stamped journal headers (## [Month],**[Month] N update) that should be integrated in-place.addable-line-range— a footnote citing a text-addressable raw file (markdown / plaintext / code / cached HTML) with noL<start>-<end>token. Exempt: PDFs, transcripts, live URLs — never flag those. Return findings only — no page bodies.
Aggregate all subagent findings in the main thread and dedup on
(type, sorted(pages), detail-entity) — a page in K tags sits in K clusters, so the same
finding can surface more than once.
Coverage note: because subagents only see their cluster, body-level findings are cluster-scoped. Pages sharing no tag with any other page are not body-checked. This is the accepted limit of tag-cluster scoping; Phase 1 (graph/string checks) still covers every page.
Phase 3 — coverage gaps, then assemble the report
First, the one body-level check that needs no page bodies: read wiki/overview.md and flag
🔵 Coverage gaps — open questions that a web search or a new ingest could answer.
Then write wiki/pages/lint-<today>.md (do not ask permission — always write this), merging
Phase 1 findings, the deduped Phase 2 findings, and the coverage gaps. The template below
shows slug references in obsidian form for readability; in the actual report you write, every
slug reference must follow the ## Emit rule from config/link-style.md:
---
title: Lint Report <today>
category: Maintenance
summary: <N> errors, <N> warnings, <N> info
tags: [lint, maintenance]
sources: []
created: <today>
updated: <today>
---
# Lint Report — <today>
## Summary
- 🔴 Errors: N
- 🟡 Warnings: N
- 🔵 Info: N
<!-- note here if any cluste
Read the complete source ↗