llm-wiki

name	llm-wiki
description	Build and maintain an LLM-owned markdown wiki inside a repository. Use when setting up a repo wiki, scaffolding a wiki root, refreshing wiki pages from repo sources, ingesting new sources, answering from the wiki, or linting for gaps, stale content, and missing cross-links.
compatibility	Requires a filesystem-backed repo with markdown support. Best when the agent can read repo files, edit files, and optionally inspect git history.
metadata	{"author":"jack-and-opencode","version":"0.1"}

LLM Wiki

Use this skill to create and maintain a persistent markdown wiki that sits between raw project sources and future questions.

The wiki is LLM-owned. The raw sources are not.

Mode Selector

Pick one primary mode before acting.

• setup: the repo does not yet have a configured wiki, or the user wants to bootstrap one
• refresh: the wiki exists and should be updated from repo sources
• ingest: the user wants to process a specific file, folder, or topic deliberately
• query: the user wants an answer from the wiki, optionally filing the result back into the wiki
• lint: the user wants a health check for stale pages, contradictions, missing pages, or weak cross-linking

If the user intent is ambiguous, choose the narrowest mode that fits and say which mode you are using.

When To Use

Use this skill when the user wants to:

• explore the idea of an LLM-maintained wiki for a repo
• bootstrap a wiki in a new repo
• refresh wiki content after source changes
• ingest a specific file, folder, or topic
• answer questions from a maintained wiki and optionally file the result
• lint the wiki for stale pages, contradictions, or missing pages

Example Prompts

These are examples of requests that should activate this skill.

• Set up an LLM wiki for this repo
• Scaffold a wiki root for this project
• Refresh the wiki after the docs changes
• Ingest docs/runbooks/adding-hetzner-arm-node.md into the wiki
• Answer this question from the wiki and save the result if it is useful
• Lint the wiki for stale or missing pages
• Does this repo have an LLM wiki, and does it need refreshing?

Default Model

Treat the wiki as a compiled knowledge layer:

• raw repo files are sources
• the wiki is a maintained synthesis
• the skill must respect the repo's configured write boundary

Do not assume a fixed wiki root such as docs/wiki/. The selected root must come from setup decisions and repo-local config.

Session-Start Check

When a repo already has a configured wiki and the current task is substantial, start with a cheap freshness check before deeper work.

1. Check whether the configured wiki root exists.
2. Read _meta/config.yaml and _meta/status.md.
3. Compare the freshness threshold against the current date.
4. If practical, look for recent repo changes in configured source roots.
5. If the wiki appears stale, tell the user and recommend refresh before or during the current task.

Do not block normal work on this check. The purpose is to prompt intelligently, not to force a refresh every time.

Quick Decision Table

Use this table to choose the path quickly.

Situation	Mode	First action
No wiki exists yet	setup	inspect repo shape and ask focused setup questions
Wiki exists and repo docs/config changed	refresh	read config and status, then scan high-signal sources
User names a specific source to process	ingest	read the named source and update the most relevant pages
User asks a question against existing wiki knowledge	query	read index.md first, then the minimum relevant pages
User asks for contradictions, gaps, or stale content	lint	inspect index, status, and representative pages

Setup Workflow

Use setup when the repo does not yet have a configured wiki.

1. Inspect the repo before making assumptions.
2. Ask a small number of focused questions.
3. Recommend a wiki root based on repo shape, but allow override.
4. Scaffold the selected wiki root.
5. Write repo-local config and schema files.
6. Generate an AGENTS.md snippet for review instead of editing AGENTS.md automatically.
7. Optionally run an initial refresh.

During setup, decide or confirm:

• wiki root
• source roots
• excluded paths
• write boundary
• freshness threshold
• whether live verification is allowed
• preferred starter page types

Keep setup focused. Prefer 3-5 questions over a long interview.

At the end of setup, clearly report:

• selected wiki root
• source roots
• exclusions
• write boundary
• whether an AGENTS.md snippet was generated
• whether an initial refresh was performed

Repo-Local Files

The scaffolded wiki should include:

• index.md
• log.md
• overview.md
• _meta/config.yaml
• _meta/schema.md
• _meta/status.md

Use these roles:

• config.yaml: machine-readable settings
• schema.md: human-readable conventions and page semantics
• status.md: freshness and sweep state
• index.md: catalog of wiki pages
• log.md: append-only timeline of wiki operations

Refresh Workflow

Use refresh to update the wiki from repo sources.

1. Read _meta/config.yaml first.
2. Read _meta/status.md to understand freshness and recent sweep state.
3. Scan configured source roots.
4. Apply exclusions aggressively.
5. Prefer high-signal sources such as docs, READMEs, key config roots, and scripts that encode operational behavior.
6. Update existing pages incrementally.
7. Create new pages only when the concept is durable and useful.
8. Refresh index.md.
9. Append a structured entry to log.md.
10. Update _meta/status.md.

Do not rewrite the entire wiki unless the user explicitly asks for a rebuild.

Prefer a small number of meaningful page updates over a huge sweep that creates thin pages.

Ingest Workflow

Use ingest for a focused update driven by a specific file, folder, or topic.

1. Identify the requested source.
2. Read only the necessary supporting context.
3. Update the most relevant existing wiki pages first.
4. Create a new page only if the source introduces a durable new concept, service, node, runbook, or query artifact.
5. Update index.md, log.md, and _meta/status.md.

Prefer folding new information into existing pages over spawning many thin pages.

Query Workflow

Use query to answer from the wiki first.

1. Read index.md to locate relevant pages.
2. Read the minimum number of pages needed to answer well.
3. Answer using wiki content and note uncertainty when pages are stale or marked unverified.
4. If the result has durable value, file it under queries/ and add it to index.md.
5. Append a query entry to log.md when the query created or substantially updated a page.

If the answer depends on stale or uncertain repo-derived information, say so plainly.

Lint Workflow

Use lint to health-check the wiki.

Look for:

• stale pages
• contradictions between pages
• missing links
• orphan pages
• obvious source gaps
• concepts mentioned repeatedly without their own page
• places where recent repo changes imply the wiki may now be incomplete

Prefer filing concrete follow-ups inside the wiki rather than giving only chat output.

When possible, categorize findings as:

• stale
• contradictory
• missing page
• weak cross-linking
• likely source drift

Freshness Model

The default model is session-autonomous, not background-autonomous.

• there is no cron
• the agent checks freshness during active sessions
• if the wiki appears stale, the agent should suggest refresh
• refresh stays explicit and reviewable

Read freshness settings from _meta/config.yaml and _meta/status.md instead of inventing your own thresholds.

Default recommendation behavior:

• if stale and relevant source files changed, recommend refresh
• if stale but no relevant changes are obvious, mention it briefly without over-prompting
• if fresh, continue normally

Write Boundaries

The wiki may write only inside the configured write boundary.

If the user wants changes to docs outside the wiki, treat them as suggested follow-up work unless the user explicitly asks for those edits.

Do not silently rewrite source documents.

Obsidian Compatibility

Assume the wiki should remain usable as a normal Obsidian vault unless repo-local config says otherwise.

This means:

• keep files as normal markdown
• use folders for page categories
• keep frontmatter simple
• avoid dependencies on external databases or services for core operation

Quality Bar

Prefer:

• a small number of strong pages
• explicit uncertainty labels
• concise summaries with source references
• incremental updates

Avoid:

• mirroring raw docs page-for-page without synthesis
• creating many low-value stub pages
• treating vendor trees and generated files as equal to human-authored sources

Templates And References

Use the starter templates in assets/ when scaffolding a new wiki.

Read references/setup-checklist.md when bootstrapping a repo. Read references/page-model.md when deciding whether to create or update a page.

Output Expectations

When you finish a wiki operation, report:

• which mode you used
• which files were created or updated
• any important uncertainties or source contradictions discovered
• whether the wiki now appears fresh or still needs follow-up