# Kmd Lint

> Health check for a markdown knowledge base (Obsidian-compatible, the LLM-wiki pattern) — personal or shared. Use whenever asked to lint, audit, check, review, or clean up a KB, on any scheduled hygiene/maintenance run, or when KB quality is in doubt (stale pages, contradictions, broken links, unprocessed sources, index drift). Drift is the KB's primary failure mode; if in doubt whether a lint pas…

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

## Install

```sh
agentstack add skill-yasik-kmd-kmd-lint
```

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

## About

# kmd-lint — KB health check

A knowledge base rots by default: indexes drift from pages, claims go stale,
duplicates accumulate, sources pile up un-ingested. Lint is the counter-force
and it is not optional — every production implementation of the LLM-wiki
pattern reports drift as *the* failure mode. Lint runs in two phases:
deterministic checks (a script — free, exhaustive) and judgment passes (you —
expensive, so spent only where scripts can't reach).

## Before you start

Locate the KB root the same way kmd-ingest does: a path you were given >
`$KMD_ROOT` > `.kmd.json` at the workspace root > a directory containing
`SCHEMA.md`/`LOG.md` > the default `kb/`. The script's `--kb` flag implements
this resolution. Then check for the **org extension**: if `.kmd.json` declares
an `"org"` key or the workspace has `_charter/ORG.md`, read
[references/org-extension.md](references/org-extension.md) — it changes how
findings are routed in Phase 3. Otherwise the core protocol below applies
as written.

## Phase 1 — mechanical checks (run the script first)

```bash
python3 scripts/lint_mechanical.py --kb  --report --agent 
```

This checks: broken wikilinks, invalid/missing frontmatter (including the
provenance rule), modified files under `sources/` (append-only violation,
via git — when the KB is not under git the script says so explicitly rather
than implying coverage), unreferenced sources (un-ingested intake), orphan
pages, page updates with no LOG entry, oversized pages, and a missing or
stale `INDEX.md` (fix: `recompile_index.py` from kmd-ingest). With
`--report` it writes a
report skeleton to `/.lint/-mechanical.md` (or the `report_dir`
configured in `.kmd.json`) with empty **Judgment findings** and **Resolution**
sections for you to fill in. Use `--format json` to process findings
programmatically.

## Phase 2 — judgment passes (what scripts cannot catch)

Read `INDEX.md` (or list pages) to plan the passes; read full pages only
where a pass flags something. Four passes, in order of value:

1. **Contradictions.** Cluster pages that speak about the same entity/topic
   (index descriptions and shared tags are good signals). Compare their
   claims. Two pages asserting incompatible facts is the highest-severity
   finding lint can produce — a KB that contradicts itself is worse than no
   KB, because it answers confidently either way.
2. **Staleness.** Pages whose `sources:` have newer material filed in
   `sources/` that they don't yet reflect; pages on volatile topics with
   old `updated` dates; claims with dates in them that have since passed.
   Flag, don't silently rewrite — the fix is a re-ingest against the newer
   source.
3. **Near-duplicates.** Pages whose titles/descriptions suggest the same
   concept split across two homes (the dedup gate at ingest time misses
   some). Propose a merge direction: which page survives, which becomes a
   redirect stub or is deleted after its unique content moves.
4. **Confidence downgrades.** Pages marked `confidence: high` whose sources
   are thin (single bare URL, no filed source) or contradicted elsewhere.
   Downgrading confidence is a cheap, honest fix you can apply directly.

## Phase 3 — triage and resolution

Every finding ends in exactly one of two places (core protocol):

- **Fixed directly** — mechanical, judgment-free repairs: a broken link whose
  target was renamed, a missing frontmatter field derivable from content, a
  confidence downgrade, an orphan page linked from the obvious related page.
  Every fix you apply is itself a KB write: follow the kmd-ingest protocol
  (bump `updated`/`author` on touched pages, validate, log with
  `--action lint`).
- **Recorded as open items** — anything requiring knowledge the linter
  doesn't have (which side of a contradiction is true, whether a merge loses
  nuance, whether a stale claim still holds): write it into the report's
  **Resolution** section as a concrete, actionable item for the KB owner.
  Un-ingested sources are open items too — each is a pending ingest.

*Org installations route instead of recording* — judgment calls go to page
authors' inboxes, intake to the owning agent. See
[references/org-extension.md](references/org-extension.md); the report still
records every handoff.

Complete the report (all three sections), then log the pass:

```bash
python3 scripts/kb_log.py --action lint --agent  \
    --title "lint pass:  errors,  warnings,  open items"
```

(`kb_log.py` ships with the kmd-ingest skill; a copy of the shared helpers is
bundled here — the log line matters more than which copy writes it.)

## What lint never does

- Rewrite page *content* wholesale — lint repairs structure and surfaces
  judgment; substantive rewrites are re-ingests
- Touch anything under `sources/` (append-only, even for lint) beyond
  restoring a tampered file to its committed state
- Hand-edit `INDEX.md` (script-generated) or write LOG.md by hand
- Silently "fix" a contradiction by picking a side — surface it; the owner
  or a re-ingest against sources decides

## Done looks like

Script run clean or findings triaged → judgment passes done over the full
page set → report with all three sections filled → open items concrete enough
to act on (or handoffs delivered, in org mode) → one LOG entry. A lint pass
that only runs the script is half a lint pass.

## Source & license

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

- **Author:** [yasik](https://github.com/yasik)
- **Source:** [yasik/kmd](https://github.com/yasik/kmd)
- **License:** MIT

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-yasik-kmd-kmd-lint
- Seller: https://agentstack.voostack.com/s/yasik
- 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%.