Skill: nkhoit/llm-wiki (version 1.2.0)

--- name: wiki description: "LLM-maintained personal knowledge base. Compile raw sources into a structured markdown wiki, auto-lint for consistency, serve as a browsable website. Inspired by Karpathy's 'LLM Knowledge Bases' workflow. Use when: user asks to create/manage a wiki, 'wiki this', 'add to wiki', 'compile raw/', 'lint the wiki', or wants a personal knowledge base. NOT for: general note-taking (use memory system), one-off Q&A, or tasks better suited to a database." --- # Wiki — LLM-Maintained Knowledge Base You maintain a personal wiki for the user. The wiki is a collection of markdown articles organized by topic. You are the compiler, editor, and librarian. ## Setup If the wiki doesn't exist yet, run `scripts/bootstrap.sh` to create the structure, install dependencies, and configure git + static serving. The wiki lives at `~/wiki/` with this structure: ``` ~/wiki/ ├── mkdocs.yml ├── docs/ │ ├── index.md ← master index (you maintain) │ ├── log.md ← chronological ingest/lint/query log (append-only) │ ├── raw/ ← inbox for unprocessed sources │ │ └── processed/ ← archived after compilation │ └── topics/ │ ├── <topic>/ │ │ ├── _index.md ← topic overview + article list │ │ └── <article>.md ← individual articles │ └── ... └── site/ ← built static site (gitignored) ``` ## Core Operations ### 1. Filing Knowledge (most common) When conversations produce durable knowledge, file it directly: 1. Determine the right topic directory (create new one if needed) 2. Write or update the article in `docs/topics/<topic>/<article>.md` 3. **Update related pages** — scan existing articles for references to the same concepts, entities, or data. Add cross-links, update numbers, note where new info supersedes old claims. A single ingest should touch every relevant page, not just the target article. 4. Update `docs/topics/<topic>/_index.md` with the new article link 5. Update `docs/index.md` stats if a new topic/article was added 6. Update `mkdocs.yml` nav section 7. Append an entry to `docs/log.md` 8. Rebuild: `scripts/build.sh` Articles should be self-contained, factual, and cross-linked where relevant. Use `See also: [Title](relative-path.md)` for connections. ### 2. Compiling from raw/ When the user drops sources in `docs/raw/` or gives you a URL: 1. Read/fetch the source material 2. Extract durable knowledge (skip ephemeral details, opinions without evidence) 3. File into appropriate topic articles (new or existing) 4. **Update related pages** — same as Filing: scan existing articles and update cross-links, numbers, or claims affected by the new source 5. Move the raw source to `docs/raw/processed/` 6. Append an entry to `docs/log.md` 7. Rebuild: `scripts/build.sh` ### 3. Linting (daily via heartbeat) Scan `~/wiki/docs/` for: - **Contradictions** — facts/numbers/claims in one article that conflict with another. Flag the specific pages and the conflicting statements. - **Stale data** — outdated references, old dates paired with "current"/"latest" language, version numbers that have been superseded - **Missing links** — references to topics without articles - **Dead cross-links** — broken `See also` links - **Orphan pages** — pages with no inbound links from other articles - **Weak pages** — articles that are too thin to be useful on their own (candidates for merging or expanding) Fix within `~/wiki/docs/`: broken links, typos, missing cross-links, orphan pages (add links from related articles). Flag to user: contradictions (with quotes from both sides), stale data, suggested new articles, weak pages. Append a lint entry to `docs/log.md`. ### 4. Filing Good Answers When a conversation produces a solid synthesized answer (comparison, analysis, deep-dive), proactively offer to file it as a wiki page. Good candidates: - Comparisons or evaluations (model benchmarks, tool comparisons) - How-to knowledge derived from troubleshooting - Synthesized research across multiple sources - Decisions with rationale These shouldn't disappear into chat history — they compound in the wiki. ### 5. Browsing The wiki is served as a static MkDocs site. After any content change, run `scripts/build.sh` to regenerate. ## Article Style Guide - **Title**: H1 at top, descriptive - **Date/context**: italicized line under title when relevant (e.g., `*Tested: 2026-04-02 on Mac mini M4 16GB*`) - **Structure**: use H2 sections, tables for comparisons, code blocks for commands - **Cross-links**: `See also: [Article](relative-path.md)` at bottom - **Be factual**: cite sources, include numbers, avoid vague claims - **Keep it dense**: this is a reference, not a blog post ## Adding New Topics 1. Create `docs/topics/<topic>/` directory 2. Create `docs/topics/<topic>/_index.md` with overview + article list 3. Add to `docs/index.md` topic list 4. Add to `mkdocs.yml` nav section ## Dependencies & System Changes This skill requires or will install the following: | Dependency | Purpose | Installed by | |---|---|---| | Python 3 | MkDocs runtime | Must be pre-installed | | mkdocs + mkdocs-material | Static site generator | `bootstrap.sh` via pipx or pip3 | | git | Version control | Must be pre-installed | ### What `bootstrap.sh` does - Creates `~/wiki/` directory structure - Installs `mkdocs` + `mkdocs-material` via pipx/pip3 **if not already installed** - Initializes a git repository - Creates a **persistent static server** as a LaunchAgent (macOS) or systemd user service (Linux) on port 8300 - The static server serves `~/wiki/site/` on `127.0.0.1` only (not publicly accessible) ### What `build.sh` does - Rebuilds the MkDocs static site - Commits all changes to git (local only by default) - Use `--push` to also push to a configured git remote (requires SSH keys or stored HTTP credentials) ### Optional: heartbeat integration You can integrate wiki linting into your agent's heartbeat cycle. This is opt-in and requires adding config to your `HEARTBEAT.md`. The heartbeat integration reads `heartbeat-state.json` (for timing) and optionally `memory/` daily notes (to detect wiki gaps). See `references/heartbeat-integration.md` for setup. ## Log (`docs/log.md`) Append-only chronological record of wiki activity. Every ingest, lint, and filed answer gets an entry. Format: ```markdown ## [YYYY-MM-DD] ingest | Article Title - Source: <URL or filename> - Pages touched: page1.md, page2.md, ... - Summary: one-line description of what was added/changed ## [YYYY-MM-DD] lint - Fixed: <list of silent fixes> - Flagged: <list of issues reported to user> ## [YYYY-MM-DD] filed | Article Title - Origin: conversation / Q&A synthesis - Summary: one-line description ``` The log is parseable with grep: `grep "^## \[" docs/log.md | tail -10` gives the last 10 entries. ## Build & Deploy Always run `scripts/build.sh` after content changes. This: 1. Rebuilds MkDocs static site 2. Commits all changes to git 3. Pushes to remote

path: references/article-template.md
content: # Example Article Template

Use this as a reference for article style and structure.

```markdown
# Article Title

*Context line — when tested, what hardware, source, etc.*

## Background

Brief context. Why this matters. 2-3 sentences max.

## Main Content

Use H2 sections to organize. Tables for comparisons:

| Thing | Metric A | Metric B |
|---|---|---|
| Option 1 | value | value |
| Option 2 | value | value |

Code blocks for commands:

\`\`\`bash
example-command --flag value
\`\`\`

## Key Findings

- Bullet points for takeaways
- Be specific — include numbers, not just "it was faster"
- Each bullet should be independently useful

## Setup / How-To (if applicable)

Step-by-step instructions if the article is procedural.

## See Also

- [Related Article](relative-path.md) — one-line description
```


path: scripts/build.sh
content: #!/bin/bash
# Build the wiki static site and commit changes.
# Usage: bash scripts/build.sh [--push]

set -euo pipefail

WIKI_DIR="${HOME}/wiki"
PUSH=false

[[ "${1:-}" == "--push" ]] && PUSH=true

cd "${WIKI_DIR}"

# Rebuild static site
echo "🔨 Building wiki..."
mkdocs build 2>&1 | grep -E "INFO|ERROR" || true

# Git commit if there are changes
if [[ -n "$(git status --porcelain)" ]]; then
  git add -A
  
  # Generate commit message from changed files
  CHANGED=$(git diff --cached --name-only | grep "^docs/" | sed 's|docs/||' | head -5)
  if [[ -n "${CHANGED}" ]]; then
    MSG="wiki: update $(echo "${CHANGED}" | tr '\n' ', ' | sed 's/,$//')"
  else
    MSG="wiki: update"
  fi
  
  git commit -m "${MSG}"
  
  if $PUSH && git remote get-url origin &>/dev/null; then
    git push
    echo "✅ Pushed to remote"
  fi
else
  echo "No changes to commit"
fi


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)