| name | kb-search |
| description | Search the project's markdown knowledge base via the GitMark CLI instead of grep cmd. Use to find where something is documented, answer "where do the docs say X", or before reading many files at random; Hits come back as `file:line · heading · snippet`. |
kb-search — search the knowledge base (GitMark)
The repo's markdown is a md + README-index + git knowledge base. Markdown is the source
of truth; the search index is derived and regenerated from it
G="python3 .claude/skills/kb-search/gitmark.py"
How to run (including /kb-search <query>)
- Index stale (docs changed since last build)? →
$G index (rebuild, fast).
$G search "<query>" -k 8 — [bm25] exact term · [trigram] substring · [fuzzy] typos/forms/Cyrillic.- Summarize the top hits (
file:line), open the 1–2 most relevant, and answer — don't reprint whole snippets.
- Bare
/kb-search (no query) → $G stat + show the /kb-search <query> syntax.
- Add
--json for machine-readable output.
- Scope — default hides historical docs (
plan/report: stale plans, one-off audits).
Add --scope all to include them, or --scope history for only those — use it when the
question is about past intent or a one-off analysis rather than current state (e.g. "what
was the original plan for X", "what was the context when we scoped X", "what did the audit
of Z find").
- Visual overview of the whole KB →
/kb-graph (separate script graph.py; HTML ontology graph).
Principles
- Markdown is the source of truth — edit
.md, never the index.
- Don't commit
.gitmark/ — it's a gitignored, rebuildable cache.
- Maintaining the KB (types, placement, links) → the
kb-maintain skill.
