wiki-kb

name	wiki-kb
description	Build and maintain a local, portable, markdown-based knowledge base. Use when the user wants to ingest documents into a wiki, check wiki health, synthesize emergent concepts, or file ephemeral knowledge. Trigger on: "ingest", "add to knowledge base", "add to wiki", "build wiki", "process documents into wiki", "lint wiki", "check wiki", "wiki health", "review the wiki", "synthesize", "find patterns", "what concepts are missing", "file this to wiki", "capture this to wiki", "import into wiki", "ingest this URL", "organize wiki", "fix wiki tags"
license	Apache-2.0
compatibility	Requires Python 3.10+. All scripts are stdlib-only.
allowed-tools	Bash(python3:*) Bash(git:*) Read Write
metadata	{"version":"1.0.0","authors":"juanje","tags":"knowledge-base, wiki, markdown, local","repository":"https://github.com/juanje/wiki-kb"}

wiki-kb

Transforms documents, conversations, and scattered knowledge into an interconnected wiki of atomic markdown pages. Works for team knowledge, technical documentation, articles, and personal research alike. Plain files, no database, no external service.

Wiki root

Resolve the wiki root path in this order:

1. Explicit path from the user.
2. WIKI_ROOT in workspace config (.env, agent config, project settings).
3. Default: ./wiki/ relative to workspace root.

All scripts accept --wiki-root <path>.

First-time setup

Create the directory, .meta/, a .gitignore (.meta/ and .staging/), index.md with # Wiki, and .meta/log.md with # Wiki log. glossary.md and tags.md are generated by scripts after the first ingest.

Copy <skill-dir>/templates/AGENTS.md to <wiki-root>/AGENTS.md, create a symlink <wiki-root>/CLAUDE.md → AGENTS.md, and copy <skill-dir>/templates/README.md to <wiki-root>/README.md. This makes the wiki self-contained: any AI assistant that opens the wiki directory can answer questions from it without the skill.

Routing

Read the corresponding reference file before starting work.

User intent	Reference file
"ingest", "add to knowledge base", "build wiki", "process documents"	references/wiki-ingest.md
"lint", "check wiki", "wiki health", "review the wiki"	references/wiki-lint.md
"synthesize", "find abstractions", "what concepts are missing"	references/wiki-synthesize.md
"file this", "add this to the wiki", "capture this"	references/wiki-file.md
"import from GitLab", "import repo", "ingest this URL"	references/wiki-import.md
"organize wiki", "move pages into folders", "reorganize"	references/wiki-organize.md
Creating entity pages (any type — see entities reference)	references/wiki-entities.md (load alongside the active operation)

Scripts

Stdlib-only Python scripts in the scripts/ directory next to this file. All accept --wiki-root <path> and --json.

Path resolution: <skill-dir> is the directory containing this SKILL.md file. Determine its absolute path and use it when invoking scripts — the wiki root and the skill directory are different locations:

python3 <skill-dir>/scripts/wiki-check.py --wiki-root <wiki-root>

Script	Purpose
scripts/wiki-check.py	Structural checks (orphans, ghosts, broken links, backlinks, frontmatter)
scripts/wiki-stats.py	Graph statistics (pages, connections, hubs)
scripts/wiki-tags.py	Tag management, synthesis heuristics, search, normalization, glossary generation
scripts/wiki-backlinks.py	Missing backlink extraction with batch splitting
scripts/wiki-log-filter.py	Skip already-processed files during ingestion
scripts/wiki-organize.py	Migrate a flat wiki into subdirectories by index category

Each reference file documents which scripts to use and when.

Gotchas

• Wiki root ≠ skill dir. The wiki lives at <wiki-root> (user's data). The scripts live at <skill-dir>/scripts/ (this repo). Never confuse the two — scripts take --wiki-root to know where the data is.
• All wiki content is English. Regardless of source language. Translate during extraction.
• Never commit .meta/. It contains local operational state (ingestion log with local paths). It must be in .gitignore.
• Every write operation ends with a git commit. If the wiki is not a git repo, the operation is incomplete.
• Every page has type and description. type classifies the page (concept for regular pages, or a specific entity type). description is a one-sentence summary for index generation and search. Both are required frontmatter fields.
• Entity type names are not tags. Don't tag pages with person, service, team, etc. — the type frontmatter field handles that. Tags describe domain topics.
• Flat namespace for filenames. Even with subdirectories, page filenames should be unique across the entire wiki (no two pages named overview.md in different subdirectories).

Wiki structure

<wiki-root>/
├── AGENTS.md
├── CLAUDE.md          → symlink to AGENTS.md
├── index.md
├── tags.md
├── glossary.md
├── <category-slug>/
│   ├── <page>.md
│   └── ...
├── <category-slug>/
│   └── ...
└── .meta/

Pages live in subdirectories named after their index category (slugified). New pages are always placed in their category's subdirectory — create it if it doesn't exist yet. A brand-new wiki starts with pages in root until categories form; once categories exist in index.md, pages go into subdirectories.

To migrate existing root-level pages into subdirectories, see references/wiki-organize.md.