Wiki

LLM-maintained personal knowledge base. Compile raw sources into a structured markdown wiki, auto-lint for consistency, serve as a browsable website. Inspire...

Security Scan

The skill's files, scripts, and instructions are consistent with a personal MkDocs-based wiki: the actions it performs (installing mkdocs, creating ~/wiki/, building the site, and running a local user service) match its stated purpose.

Purpose & Capability

The skill claims to create and maintain a markdown wiki and includes scripts and prose that do exactly that: bootstrap.mkdocs, create ~/wiki structure, build the site, commit changes, and optionally serve it locally. Required tools (python/mkdocs/git) are coherent with the stated purpose.

Instruction Scope

Most runtime instructions are scoped to ~/wiki/ (creating, updating, linting, building). The optional heartbeat integration (explicitly labelled 'opt-in' in references/heartbeat-integration.md) reads heartbeat-state.json and, unless edited out, can read memory/ daily notes outside ~/wiki/ for gap detection; this is a documented opt-in behavior and not enabled by default, but it is the only part that touches files outside the wiki directory and could surface personal data.

Install Mechanism

There is no packaged install spec in the registry; the included bootstrap.sh installs mkdocs via pipx or pip3 if mkdocs is absent. Installing Python packages via pipx/pip3 is expected for a MkDocs workflow, but it does write files and may invoke pip operations on the host. bootstrap.sh also writes LaunchAgent (macOS) or systemd user service files and enables them, which persistently creates a local static server.

Credentials

The skill does not require environment variables or credentials. build.sh can push to a remote only if the user passes --push and a git remote is configured (it relies on existing SSH keys or HTTP credentials in the user's git config). No secret-exfiltration mechanisms or unexpected credential requests are present.

Persistence & Privilege

bootstrap.sh creates and enables a user-level persistent static server (LaunchAgent or systemd --user). This is a reasonable action for a local wiki but does modify user-level service config in the home directory and will persist across reboots. The skill is not marked always:true and cannot force-enable itself outside user invocation.

Assessment

This skill appears to do what it says: create and maintain a local MkDocs wiki. Before installing or running bootstrap.sh, review the scripts yourself (they're included) and decide whether you want a persistent user service created in ~/Library/LaunchAgents or ~/.config/systemd/user. If you do not want the heartbeat integration to read files outside ~/wiki/, remove the gap-detection step that reads heartbeat-state.json and memory/ daily notes. Only use --push with build.sh if you intentionally want to push to a remote and have reviewed the remote and credentials. If you are uncomfortable with pip installs, install mkdocs/mkdocs-material manually and re-run bootstrap.sh with mkdocs already present.

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:

## [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