How to use the Wiki Lint Health Check agent skill

What the wiki-lint skill makes the agent do

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task. This skill tells the agent to run a deterministic lint engine, a script that inspects the state of your vault and reports results. The engine checks graph, link, frontmatter, provenance-ledger, empty-section and stale-index findings.

The skill only observes and reports. It does not create reports, dashboards, canvases or stubs, and it does not fix anything. Any repair must be a separate step in which you choose the specific findings to address and review the changes before they are applied.

• Dead or ambiguous links
• Orphan pages
• Required frontmatter gaps, including a missing title
• Empty sections
• Stale index entries
• Source/claim ledger contract violations

Install the wiki-lint skill

Download the ZIP for skills/wiki-lint from this page and unzip it into one of these locations: ~/.claude/skills/ for your personal skills, or .claude/skills/ inside a project folder for skills that apply only to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

The skill needs a local installed copy of the claude-obsidian product root, because the lint engine lives there at scripts/claude-obsidian.py. The skill's SKILL.md resolves that path from its own location, so the product root must be installed on the same machine as the skill.

Check your requirements

You need Python 3, since the skill runs python3 on scripts/claude-obsidian.py. You also need an Obsidian vault on the local filesystem. The skill is not designed for vaults that are not Obsidian-style Markdown wikis, because the engine is tailored to that layout.

The skill runs scripts, and it does not use the network according to its listing.

• Python 3 installed and available as python3
• A local installed copy of the claude-obsidian product root containing the lint engine
• An Obsidian vault on your local disk

Trigger the skill with natural requests

You do not need to type a command. The skill's description lists the phrases that should activate it, including lint, vault health check, audit wiki health, find orphans, find dead links, frontmatter audit, provenance audit and wiki audit. Name the vault you want checked, because the agent must resolve the user vault before it runs anything.

If you want the output in a form that can be pasted elsewhere, ask for a Markdown report. The agent returns it in chat or stdout; it does not write the report into the vault.

• Run a vault health check on my Obsidian vault at /path/to/vault
• Find dead links and orphan pages in my wiki
• Do a frontmatter audit and tell me which pages are missing a title
• Give me a wiki audit as Markdown

Run the lint command yourself

The agent runs the engine with the commands below. $VAULT is the path to your vault and $CORE points to the engine script inside the product root. You can run these yourself to see the same output.

The --exclude flag is repeatable and takes a glob. It removes matching paths, such as a scratchpad folder, from page, link, orphan, frontmatter, empty-section and stale-index scanning. The --strict flag makes the command exit nonzero when there are findings, which is useful in automation. Lint remains read-only either way.

• --format markdown produces a Markdown rendering
• --exclude GLOB scopes a path out of scanning and can be repeated
• --strict returns a nonzero exit code for findings

Read the findings correctly

The agent keeps the engine's paths, line numbers, targets, categories and counts, and groups findings by likely impact: broken navigation first, then ambiguous resolution, metadata quality and maintainability. An orphan page may be intentional, and an ambiguous basename needs a path-qualified link. The agent should not infer intent from a finding alone.

The parser understands Obsidian wikilinks and embeds, Markdown links, aliases, heading and block fragments, escaped aliases and code fences. It skips dot-prefixed directories by default and honors .gitignore files inside the vault. When a link is ambiguous between a page and a gitignored file such as a build artifact, the gitignored candidate is dropped.

The engine does not perform semantic, stylistic or prose-level contradiction analysis. If you need a check on meaning or writing quality, this skill will not provide it.

• Treat allowlisted findings as policy, not proof that the target exists
• Separate facts reported by the engine from suggested fixes

Fix findings through a separate, reviewed process

The skill never auto-fixes a lint result. When you choose specific findings to repair, the agent re-reads each target and records its SHA-256, drafts only the changes you selected, and builds a single repair bundle with a new operation ID. It shows you the exact changed paths, applies changes only after your separate review, and then re-runs lint read-only to compare results.

Deleting or merging pages requires explicit consent. Lint never applies the transaction itself and never commits to Git. The skill points to the operation transaction contract in the product's references for the full flow.