PromptWorks/kblinter/SKILL.md

name	description
kblinter	Run the knowledge-base linter against the Obsidian vault at D:\Repos\Obsidian and surface the findings. Use whenever the user asks to lint, audit, or check the health of the vault/Second Brain. Triggers: /kblinter, "lint the vault", "audit my notes", "check vault health", "run the kb linter", "find orphan notes", "find broken links in the vault".

kblinter — Vault Knowledge Base Linter

Wrapper around D:\Repos\Obsidian\meta\scripts\lint.py. The script implements the checks defined in AGENTS.md §5.3.

Vault layers (drives which checks apply)

Layer	Lives in	Lint behavior
Raw	Transcripts/, 00 - Chats/, Attachments/, *.vtt, *.msg	Skipped — never linted
Wiki	01 - Daily/, 02 - Meetings/, 03 - Squads/, 04 - Connects/ (except Drafts), 05 - Resources/	Full schema enforcement
Workshop	04 - Connects/Drafts/ (plus any path in WORKSHOP_DIRS in lint.py)	Exempt from frontmatter / orphan / broken-link / duplicate / meeting-provenance. Still checked for stale + sensitivity.
Schema	AGENTS.md, meta/, 99 - Templates/, any Templates/ subfolder	Skipped from most content checks

What it checks

Check	Rule	Layers affected
YAML parse errors	Frontmatter block exists but YAML invalid	wiki
Missing frontmatter	Wiki-layer page missing required keys for its type	wiki
Orphan wiki pages	No inbound [[wiki link]] from any other note (excludes type: daily and type: moc)	wiki
Stale pages	status: active updated >30d ago; status: draft updated >90d ago	wiki + workshop
Broken wiki links	[[...]] that doesn't resolve	wiki
Sensitivity mismatch	Body contains "Confidential" / customer markers without sensitivity: frontmatter	wiki + workshop
Duplicate canonical keys	Multiple notes with same (parent_dir, date, type, stem)	wiki
Meeting provenance	Wiki page under 03 - Squads/*/Meetings/ lacking a sources: or inline [[link]] to 02 - Meetings/ or Transcripts/	wiki
Transcripts inbox backlog	Files in Transcripts/ >7 days old	n/a
MOC gaps	Squad subfolder with >10 wiki pages but no MOC hub note	n/a

The linter NEVER auto-fixes. It writes a Markdown report and exits.

Canonical vs squad-side meetings

The vault deliberately keeps meetings in two places — both are valid type: meeting:

• 02 - Meetings/YYYY-MM-DD - <Title>/ = canonical record (raw VTT + auto summary). Chronological, one folder per meeting.
• 03 - Squads/<name>/Meetings/ = squad-lens commentary. Organized by squad. MUST sources: link back to the canonical record (enforced by the meeting_provenance check).

When fixing a meeting_provenance gap: add sources: ["[[02 - Meetings/YYYY-MM-DD - .../summary]]"] (or the relevant VTT path) to the squad-side note's frontmatter. The check also accepts inline [[02 - Meetings/...]] wikilinks in the body.

How to run

Default (write report)

python D:\Repos\Obsidian\meta\scripts\lint.py

Writes D:\Repos\Obsidian\meta\lint-report-YYYY-MM-DD.md. Prints a one-line summary.

JSON

python D:\Repos\Obsidian\meta\scripts\lint.py --json

Custom output / alternate vault

python D:\Repos\Obsidian\meta\scripts\lint.py --out X --vault Y

Default workflow when invoked

1. Run the linter. Overwriting today's report is fine.
2. Read the report.
3. Summarize to the user:
   • Total + per-check counts
   • Top 5–10 most-actionable items (priority: broken links > sensitivity mismatch > meeting provenance > duplicates > frontmatter > orphans)
   • Inbox backlog items — concrete unblocked actions
   • MOC gaps — suggest a name
4. Offer to fix specific issues. NEVER fix without explicit approval. Common fixes:
   • Add missing frontmatter (consider meta/scripts/frontmatter_backfill.py --dry-run first)
   • Repair a broken link
   • Add sensitivity label
   • Add sources: to a squad-side meeting note (for meeting_provenance gaps)
   • Create a missing MOC hub note
5. Append a log line to D:\Repos\Obsidian\meta\log.md: <ISO timestamp> | kblinter | lint | meta/lint-report-YYYY-MM-DD.md | <total> issues | <per-check breakdown>

Adding a new workshop path

Edit WORKSHOP_DIRS at the top of meta/scripts/lint.py:

WORKSHOP_DIRS = {
    "04 - Connects/Drafts",
    "some/new/scratch/area",   # add here
}

Update AGENTS.md §1 and §2 to document the new workshop path.

Don'ts

• Don't auto-edit any wiki page based on lint findings without explicit approval.
• Don't relax a rule because it found something — update AGENTS.md deliberately instead.
• Don't summarize the entire report verbatim — pick the most actionable items.
• Don't run on D:\Repos\TradeTrail or any other directory. Hard-coded for the Obsidian vault.

When the script fails

Surface stderr verbatim and suggest:

• python -c "import yaml" (PyYAML required)
• Check D:\Repos\Obsidian\meta\scripts\lint.py exists
• --json for raw output

Extending the linter

New checks live in lint.py registered in the CHECKS tuple. Each check takes list[Note] and returns list[dict] with path and msg keys.

When adding a check:

1. Decide which layers it applies to (filter by n.layer early)
2. Document in AGENTS.md §5.3
3. Update the "What it checks" table here
4. Add a smoke test