Markdown knowledge-base lint

A personal or team knowledge base rots quietly: links break when files move, notes lose their way in from the rest of the base, "next sprint" stops being true, and a later note silently contradicts a recorded decision. Small bases (up to a few hundred notes) fit in an agent's context, so this skill reads all of it, checks every rule below, and reports. It does not change anything until the user says which findings to act on.

1. Find the schema

Look at the base's root for a file describing its conventions: CLAUDE.md, AGENTS.md, README.md, SCHEMA.md, or an Obsidian .obsidian/ folder. Read it. Folder purposes, required frontmatter, and which folders are immutable or auto-generated all come from there. Where the schema and this skill disagree, the schema wins.

Without a schema, use these defaults and say so at the top of the report:

• Required frontmatter: title. created is recommended, not required.
• Immutable folder: decisions/ (or adr/). The one allowed edit is a status line marking it superseded.
• Exempt from orphan checks: README.md / index.md files, and journal-style folders (daily/, journal/, logs/, dated files).
• Excluded entirely: dot-folders, node_modules/, anything the schema calls generated or mirrored.

2. Read every note

Glob **/*.md minus exclusions. Whole-file reads, not chunks. For each note track: path, parsed frontmatter, H1, outbound links in all three forms ([text](relative/path.md), [[wikilink]] / [[wikilink|alias]], and paths listed in a frontmatter links: field), tags, dates.

Resolve links the way the base does: relative markdown links against the note's folder; wikilinks by filename anywhere in the base (case-insensitive, .md optional, #heading suffix ignored). A link to a non-markdown file that exists (image, PDF) is valid.

3. Checks

Each finding: severity, path, one-sentence description, suggested fix.

High

• Broken link: a markdown link, wikilink or links: entry that resolves to nothing. Suggest the likeliest intended target if a near-match exists (renamed or moved file).
• Edited decision: a decision record whose recorded view has been changed rather than superseded (check git history if available; otherwise flag only if the note itself shows signs, such as a "changed from" line).

Medium

• Missing required frontmatter (per schema, or the default title), or unparseable YAML.
• Missing reciprocal link, only when the base uses a frontmatter links: field and its schema expects symmetry: A lists B, B does not list A.
• Orphan: zero inbound links from any other note. Skip exempt files. For each real orphan, suggest the hub that should link to it.
• Decision contradiction: a later note asserts something a decision record rules out (different tool, reversed policy) with no superseding decision. Flag for the user; never resolve. It may mean the decision is outdated, the later note is wrong, or both hold in different contexts.
• Stale temporal phrasing: "next week", "this sprint", "currently", "this quarter", "in the coming days", "soon" in a note whose created or updated date is more than six weeks before today. Quote the phrase and the age.
• Aged open marker: TBD / TBC / "open question" / "to be decided" in a note last touched more than three months ago.

Low

• H1 differs from frontmatter title.
• Tag inconsistency: the same tag in different casing or separators (Data-Platform, data_platform, data-platform). Suggest the majority form.
• Emergent hub candidate: a tag on four or more notes with no note of that name acting as a hub. Suggest a hub path.
• Long-untouched note in a fast-moving folder (projects, strategy) per the schema: candidate for review, not necessarily edit.

4. Report

Write the report (to the path the user names, or to chat). Top block:

• notes scanned, and which schema or defaults were applied
• counts by severity
• anything systemic ("9 notes link to old-folder/: the folder was probably renamed")

Then findings grouped by severity, then by folder, one line each:

[HIGH] path/to/note.md: <what is wrong>. Fix: <suggested edit>.

Do not report exempt files as orphans, valid wikilinks as broken, or superseded decisions as contradictions. A noisy report gets ignored; a false positive costs more trust than a miss.

5. Fix, only on approval

After the report, offer two batches:

• Mechanical: broken links with a clear target, missing reciprocal links, tag casing, H1/title mismatches. Safe to do together.
• Judgement: orphans, contradictions, stale phrasing, aged markers. Each needs the user's call.

Make approved edits in one pass. If the base is a git repository, offer a single commit for them; never push.

Never:

• edit a decision record's substance to "fix" a contradiction
• delete an orphan
• touch generated or mirrored folders
• lint a copy and report it as the live base