kb-lint
starsforks
How to install kb-lint?
stjbrown/agent-knowledge/kb-lint
$npx -y skills add stjbrown/agent-knowledge --skill kb-lintHealth-check a knowledge bundle for conformance and drift; optionally auto-fix safe issues.
SKILL.md
| 1 | # kb-lint — health-check the bundle |
| 2 | |
| 3 | Keep a [bundle](../kb/SKILL.md) trustworthy as it **compounds** by catching **drift** — the decay a |
| 4 | growing knowledge base accumulates. Two passes: a **deterministic conformance** check (mechanical, |
| 5 | scripted) and a **drift audit** (fuzzy, judgment). Run both; report findings by severity. With |
| 6 | `fix`, repair what is safe. |
| 7 | |
| 8 | ## 1. Conformance (deterministic) |
| 9 | |
| 10 | Run the bundled checker against the target bundle (default `knowledge/`): |
| 11 | |
| 12 | ``` |
| 13 | python3 "${CLAUDE_SKILL_DIR}/scripts/conformance.py" <bundle-dir> |
| 14 | ``` |
| 15 | |
| 16 | It reports **ERROR** (a hard [SPEC](../kb/reference/SPEC.md) §9 failure — no parseable frontmatter, |
| 17 | or a missing/empty `type`) and **warn** (soft: broken links, non-ISO log dates). Broken links are |
| 18 | explicitly tolerated by the spec (§5.3) — never a conformance failure. |
| 19 | |
| 20 | **Completion criterion:** the checker has run and every ERROR it reported is listed for the report |
| 21 | (and fixed, if in `fix` mode). |
| 22 | |
| 23 | ## 2. Drift audit (judgment) |
| 24 | |
| 25 | The checker can't see meaning. Audit the bundle for the ways a compounding artifact rots — this is |
| 26 | the legwork that makes lint worth running. Cover every check: |
| 27 | |
| 28 | - **Contradictions** — concepts asserting conflicting facts that aren't linked `conflicts_with`. |
| 29 | - **Stale claims** — statements a newer source has superseded but that were never marked |
| 30 | `superseded_by`; overviews behind their children. |
| 31 | - **Orphans** — concepts with zero inbound [cross-links](../kb/reference/glossary.md) (index/log |
| 32 | exempt; overviews exempt). |
| 33 | - **Missing cross-references** — concepts about the same entity/theme that don't link to each other. |
| 34 | - **Coverage gaps** — entities named repeatedly across concepts but lacking their own concept; data |
| 35 | gaps a source or web search could fill. |
| 36 | - **Provenance gaps** — concepts making external claims with no `# Citations` / Reference. |
| 37 | |
| 38 | **Completion criterion:** every check above has been run across the whole bundle and its findings |
| 39 | recorded — not a sample. |
| 40 | |
| 41 | ## 3. Report |
| 42 | |
| 43 | Present findings grouped by check, each tagged: |
| 44 | |
| 45 | - **Error** — §9 conformance failures. The bundle is non-conformant until fixed. |
| 46 | - **Warning** — drift that degrades trust (contradictions, stale claims, orphans, broken links). |
| 47 | - **Info** — suggestions (coverage gaps, new concepts or sources worth adding). |
| 48 | |
| 49 | Turn coverage gaps into concrete next moves: questions to investigate, sources to |
| 50 | [ingest](../kb-ingest/SKILL.md). Append a dated summary (counts + notable findings) to the bundle's |
| 51 | `log.md` — append-only. |
| 52 | |
| 53 | **Completion criterion:** a severity-grouped report is delivered and a `log.md` summary appended. |
| 54 | |
| 55 | ## Fix mode |
| 56 | |
| 57 | If invoked with `fix`, repair only what is **safe and unambiguous**, then re-report what was fixed |
| 58 | vs. what needs a human: |
| 59 | |
| 60 | - **Safe to auto-fix:** stale overviews (regenerate from children), missing cross-links, malformed |
| 61 | log dates, broken links with an obvious target, index entries out of sync with files. |
| 62 | - **Never auto-fix:** anything that changes a claim's meaning. A contradiction or a stale *claim* is |
| 63 | resolved by [ingest](../kb-ingest/SKILL.md) under the [trust model](../kb/reference/trust-model.md) |
| 64 | (**supersede**/**conflict**) — never by editing meaning in place here. Flag these for the user. |
| 65 | |
| 66 | **Completion criterion:** every safe issue is fixed and every meaning-level issue is flagged (not |
| 67 | touched); the re-report distinguishes the two. |
People who liked this also viewed
6 picksType
- azure-aiUse for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector searSkillsJul 2026
- just-scrapeSearch, scrape, crawl, extract structured data, and monitor web pages via the ScrapeGraph AI CLI. Use when the user asks to search the web, scrape a webpage, grab content from a URL, extract JSON fromSkillsJul 2026
- firecrawlCLI and Agent Skill for Firecrawl - Add scrape, search, and browsing capabilities to your AI agentsSkillsJul 2026
- firecrawl-searchWeb search with full page content extraction. Use this skill whenever the user asks to search the web, find articles, research a topic, look something up, find recent news, discover sources, or says "SkillsJul 2026
- firecrawl-agentAI-powered autonomous data extraction that navigates complex sites and returns structured JSON. Use this skill when the user wants structured data from websites, needs to extract pricing tiers, producSkillsJul 2026
- firecrawl-mapDiscover and list all URLs on a website, with optional search filtering. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where sSkillsJul 2026
