# Lint

> Health-check a markdown knowledge base. Find broken links, orphan notes, missing frontmatter, inconsistent facts, duplicate concepts, and suggest new articles to fill gaps. Use when the user says 'lint my wiki', 'check my KB health', 'find inconsistencies', 'what should I write next'. Part of the knowledge-base pack.

- **Type:** Skill
- **Install:** `agentstack add skill-markfive-proto-obsidian-brain-vault-lint`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [markfive-proto](https://agentstack.voostack.com/s/markfive-proto)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [markfive-proto](https://github.com/markfive-proto)
- **Source:** https://github.com/markfive-proto/obsidian-brain-vault/tree/main/skills/lint
- **Website:** https://supermarcus.ai/brain-os

## Install

```sh
agentstack add skill-markfive-proto-obsidian-brain-vault-lint
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Lint Pack — "Keep my KB clean and complete"

`lint` is the **maintenance layer**. A growing wiki rots silently. This skill surfaces rot, impute-able gaps, and high-value next writes.

## Output convention

Lint always writes a report to `outputs/lint/-.md`. Never replies in chat only.

## Commands

### /lint — Full health check

When the user invokes `/lint`:

1. Run all the sub-checks below in parallel, merge findings.
2. Write a single report at `outputs/lint/-full.md`.
3. Summarize chat-side: totals per severity (error / warn / info) and link to the report.

### Sub-checks (each is also runnable individually)

#### /lint-links — Broken links

- For every `[[wikilink]]` in the vault, check the target file exists.
- For every markdown `[text](relative-path)` link, check the path resolves.
- For every external URL, optionally HEAD-request and flag 404s (off by default; opt-in via `--check-urls`).
- Report: file, line number, bad target, suggested fix (closest existing filename via fuzzy match).

#### /lint-orphans — Disconnected notes

- A note is an **orphan** if: 0 incoming wikilinks AND 0 outgoing wikilinks AND not in a designated "inbox" folder.
- Report each orphan with its first 200 chars of content.
- Suggest: delete / link to existing concept / promote to concept page.

#### /lint-frontmatter — Missing or invalid metadata

- Every file under `compiled/` should have frontmatter with at least: `title`, `type`, `tags`, `last_updated`.
- Every file under `raw/` should have: `source_type`, `source_url` (if applicable), `tags`.
- Report missing fields with suggested values (infer from content/filename).

#### /lint-duplicates — Concept dedupe

- Group `compiled/concepts/*.md` by stemmed title.
- Flag pairs/triples that are likely duplicates (e.g., `transformer.md` and `transformers.md`, `self-attention.md` and `scaled-dot-product-attention.md`).
- Suggest canonical name and merge plan (do NOT merge automatically).

#### /lint-inconsistencies — Conflicting facts

- Build a fact map: for each concept, extract atomic factual claims (dates, numbers, named-entity relationships).
- Cross-check claims across sources.
- Flag contradictions. Example: "Raw A says founded 2017; raw B says founded 2018."
- Suggest resolution: which source is more authoritative, or mark as disputed.

#### /lint-gaps — New-article candidates

Use two signals:
1. **High-degree stubs:** any concept page with `sources_count >= 3` but TL;DR ` to refresh."

#### /lint-tag-drift — Tag hygiene

- Find tags used only once or twice (probably typos or singletons).
- Find near-duplicate tags (`#ml-ops` vs `#mlops`).
- Suggest canonicalization.

#### /lint-connections — Suggest new links

- For each pair of concept pages sharing 2+ tags AND 3+ raw sources in common, check whether they already link to each other.
- If not, propose mutual wikilinks with a 1-line reason.

## Severity model

| Level | Meaning | Example |
|---|---|---|
| error | Broken state; user action required | Broken wikilink target |
| warn | Degraded quality | Missing frontmatter field |
| info | Suggestion / improvement | Tag drift, link opportunity |

Report counts per severity at the top of the lint output.

## Report template

```markdown
---
title: Lint Report — 
type: lint-report
run: full
tags: [output, lint]
---

# Lint Report — 

## Summary
- Errors: 
- Warnings: 
- Info: 
- Notes scanned: 

## Errors

### Broken links ()
- `[[missing-concept]]` in [[file]] line  → suggest [[closest-existing]]

### Other errors
...

## Warnings
...

## Info / suggestions
...

## Next-to-write (prioritized)
1.  — reason: 5 dangling links, 3 open questions
2. ...
```

## Auto-fix mode (opt-in)

When the user passes `/lint --fix` or says "fix the safe stuff":

- Safe auto-fixes only:
  - Add missing `last_updated` from file mtime.
  - Canonicalize near-duplicate tags with the canonical form.
  - Remove trailing whitespace.
- Unsafe (NEVER auto-fix):
  - Merging concept pages.
  - Rewriting content.
  - Deleting orphans.

Report every auto-fix applied with file + diff.

## Scheduling

Recommend to the user: run `/lint` after every 10+ ingests, or weekly. Can be automated via `cron` or `schedule` skill.

## Related skills (same pack)

- `[[ingest]]` — upstream; lint suggests new ingests
- `[[compile]]` — lint flags things compile missed
- `[[qa]]` — outputs of qa are NOT linted as content (only format)
- `[[render]]` — lint reports can be rendered as dashboards

## Attribution

Pack inspired by Karpathy's "LLM health checks over the wiki" practice — surfacing inconsistencies, imputing gaps, suggesting next writes.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [markfive-proto](https://github.com/markfive-proto)
- **Source:** [markfive-proto/obsidian-brain-vault](https://github.com/markfive-proto/obsidian-brain-vault)
- **License:** MIT
- **Homepage:** https://supermarcus.ai/brain-os

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-markfive-proto-obsidian-brain-vault-lint
- Seller: https://agentstack.voostack.com/s/markfive-proto
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.