| 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:
- Explicit path from the user.
WIKI_ROOT in workspace config (.env, agent config, project settings).- 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.
