# Knowledge Base > Create and maintain a Markdown knowledge base that any AI agent can read, search, and update. Use when the user wants to start a knowledge base, add or update notes, organize docs/notes for an agent or LLM to consume, build an index of notes, or run a cleanup/maintenance pass on an existing MD knowledge base. Triggers include "knowledge base", "KB", "notes for the agent", "index of notes", "second brain", "docs for AI context", "add a note", "update the KB". - Skill: `wonderwhy-er/knowledge-base` (Agent Skill) - Install (CLI): `npx skillmds add wonderwhy-er/knowledge-base` - Raw SKILL.md: https://api.skillmd.com/api/skills/wonderwhy-er/knowledge-base/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: wonderwhy-er (https://skillmd.com/u/wonderwhy-er) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/wonderwhy-er/knowledge-base --- # Knowledge Base (Markdown, agent-readable) A knowledge base (KB) here is a folder of Markdown files designed so **any** AI agent can navigate it without a vector database: the agent reads one index file, picks the relevant notes by their descriptions, and opens only those. Keep the whole KB readable and the index lean — the index is what gets loaded into context, so it must be high-signal. Apply the rules below when creating a new KB, adding/editing notes, or doing a maintenance pass. When the user's request is ambiguous (new KB vs. add note vs. cleanup), ask which one before acting. ## Core principles (the "why") 1. **Index-first navigation.** The index is a map, not a container. An agent reads `INDEX.md`, selects notes by their one-line descriptions, then opens only those files. No note is "in" the KB unless it's registered in the index. 2. **Atomicity.** One topic per note. If a title needs an "and", it's probably two notes. Atomic notes are easier to find, link, and reuse. 3. **Stable IDs.** Every note has a permanent ID that never changes and is never reused, so links survive renames and moves. 4. **Linked with reason.** When two notes connect, state *why* (prerequisite, supports, contrasts, see-also). Connections carry as much value as the notes. 5. **Lean instructions.** Keep `INDEX.md` instructions short and high-signal — it competes for the agent's context budget. Bodies load on demand. 6. **Structured for retrieval.** Clear H1 title and H2/H3 sections so an agent can grab the relevant slice of a note, not the whole thing. ## Folder structure (nested by topic) ``` knowledge-base/ INDEX.md # entry point: instructions + full note registry topics/ / _topic.md # topic map: what this topic covers + its notes .md # one atomic note assets/ # images / attachments referenced by notes ``` - Topic folders are short, lowercase nouns (`auth`, `billing`, `deploys`). - `_topic.md` is the topic-level map of content (MOC): a short intro plus links to every note in that topic. It is a convenience view; `INDEX.md` remains the source of truth. ## Naming rules - Lowercase **kebab-case**, predictable and greppable: `topics/auth/session-tokens.md`. - No spaces, no uppercase, no dates in filenames (dates live in frontmatter). - The filename slug should match the note's `id` slug portion. ## Required frontmatter (every note) ```yaml --- id: 20260618-session-tokens # ID scheme: YYYYMMDD-slug. Stable. Never reuse or change. title: Session tokens # human title, also the note's H1 tags: [auth, security] # only tags from the controlled list in INDEX.md created: 2026-06-18 updated: 2026-06-18 related: [20260618-auth-flow] # IDs of linked notes summary: One scannable sentence describing what this note covers. --- ``` - `id`: `YYYYMMDD-slug`. Sortable, readable, stable. Different-titled same-day notes differ by slug; if two same-day notes would collide on the same slug, append `-2`, `-3`, … (check the `INDEX.md` registry before assigning). Once assigned, the id is permanent. - `summary`: this exact sentence is what goes in the index registry — write it to help an agent decide whether to open the note. - `updated`: bump it whenever the body changes. ## Note body shape ```markdown # Session tokens > Summary: One sentence (mirrors frontmatter summary). ## Context Why this note exists / when it applies. ## Details The actual content, in short H2/H3 sections. ## Related - [Auth flow](auth-flow.md) — prerequisite: tokens are issued during the auth flow. - [Rate limiting](../api/rate-limiting.md) — see-also: tokens carry the rate-limit key. ``` - Use **relative links** between notes and annotate the relationship in a phrase. - Every link target should also appear in the note's `related` frontmatter. ## INDEX.md (the single source of truth) `INDEX.md` has two parts: operating instructions for agents, and the registry. ```markdown # Knowledge Base — Index ## How to use this KB (for agents) 1. Read this index first. Pick notes by their descriptions; open only those. 2. To answer a question, prefer opening 1–3 specific notes over scanning everything. 3. Cite the note `id` when you use information from it. ## How to update this KB (for agents) - New idea → create a new note (atomic). Same idea changed → edit the note in place and bump `updated`. - Any create / rename / delete MUST update this registry and the topic's `_topic.md` in the same change. - Use only tags from the controlled vocabulary below; add a new tag here before using it. ## Controlled tags `auth`, `security`, `billing`, `api`, `ops` ## Registry ### auth - `20260618-auth-flow` — **Authentication flow** — `topics/auth/auth-flow.md` — How a user session is established end to end. - `20260618-session-tokens` — **Session tokens** — `topics/auth/session-tokens.md` — Token format, lifetime, and rotation. ### billing - `20260618-invoicing` — **Invoicing** — `topics/billing/invoicing.md` — How invoices are generated and sent. ``` Registry line format: `` `id` — **Title** — `path` — one-line description.`` ## _topic.md (topic map) ```markdown # Auth Notes covering authentication, sessions, and access control. - [Authentication flow](auth-flow.md) — how a session is established. - [Session tokens](session-tokens.md) — token format, lifetime, rotation. ``` ## Workflows ### Create a new KB 1. `create_directory` for the folder structure above. 2. `write_file` `INDEX.md` with the instructions block, an empty controlled-tag list, and an empty registry. 3. Add the first topic folder + `_topic.md`, then the first note (each via `write_file`). 4. Register the note in `INDEX.md` and link it from `_topic.md` — `edit_block` both so you touch only the changed lines. ### Add a note 1. Pick or create the topic folder (`list_directory` to see what's there). 2. `write_file` the note (kebab-case slug) with full frontmatter and the body shape. 3. Add cross-links (and mirror them in `related`). 4. Register it in `INDEX.md` and link it in `_topic.md` with `edit_block` — same change. ### Update a note - Same idea, new information → `edit_block` the note in place, bump `updated`, and `edit_block` the registry line if the scope changed. - Genuinely new idea → `write_file` a new atomic note instead of expanding this one. ### Maintenance pass (run on demand) Use `start_search` (ripgrep) for text scans and `get_file_info` / `list_directory` for existence checks — together they make this tractable at scale: - **Orphans** (no *inbound* links — outbound doesn't matter): `start_search` the KB for the note's `id` and filename slug, then discount the self-matches that always exist — the note's own file, `INDEX.md`, and its `_topic.md`. Anything left is a genuine inbound reference; nothing left = orphan, so link it from a relevant note/MOC or archive it. - **Broken links / drift**: don't infer resolution from a text hit — a string existing doesn't mean the file does. Confirm each registry path and `related:` target exists with `get_file_info` (or `list_directory` per topic), and that every file on disk is registered. Use a text compare only for the titles/summaries-out-of-sync half. - **Non-atomic notes**: notes that grew to cover multiple topics → split them. - **Duplicates**: near-identical notes → merge, keep one `id`, redirect links. - **Tag sprawl**: read the controlled list from `INDEX.md`, then `start_search` the frontmatter `tags:` lines and flag any tag not on the list → reconcile. Pull candidates in bulk with `read_multiple_files`, apply fixes with `edit_block`, and report what changed. ## Checklist before finishing any KB edit - [ ] Every new/changed note has complete, valid frontmatter. - [ ] `id` is unique and unchanged; filename slug matches the id slug. - [ ] All links resolve and are mirrored in `related`. - [ ] `INDEX.md` registry and the topic `_topic.md` reflect the change. - [ ] Tags are from the controlled vocabulary. - [ ] `updated` bumped on every changed note.