knowledge-base-framework/skills/knowledge-base-read/SKILL.md

name, description

name	description
knowledge-base-read	Read and query the knowledge-base vault — a personal docs-as-code knowledge database (PARA-organized). Use when the user asks what is known about a repo, policy, decision (ADR), area, or project; wants context before working in a repo; or asks to find/navigate notes by tag, type, repo, or link. Resolves the question against the Markdown notes and the generated graph index.

Read the Knowledge Base

This vault is a personal docs-as-code knowledge database, organized with the PARA method. Markdown is the source of truth; index/graph.json is a generated navigation index. Use this skill to answer questions FROM the vault and to surface the exact notes that back the answer.

Call read_instructions on knowledge-database to read the framework's AGENTS.md and AGENT_QUERY_GUIDE.md before querying the vault. These documents are not data-vault nodes. If unavailable, report the missing instructions. This skill is read-only — do not modify notes here.

Vault access

The knowledge-database MCP server is the only interface for vault access. Use graph_summary to orient, graph_search_nodes to find notes, graph_neighbors to traverse links, and read_note to read the source. Use refresh_graph when the generated index is stale. Skills and operational documentation belong to the framework; never infer the data vault from this skill's file location.

Layout (PARA)

01_projects/                 active efforts with a goal and an end
02_areas/                    ongoing standards: policies, value-stream areas, decisions
02_areas/decisions/          global ADRs
03_resources/meta/           taxonomy + note templates
03_resources/repos/<repo>/   per-repo info.md (+ decisions/)
03_resources/repos/repo-landscape.md   index of documented repos
04_archives/                 inactive items
index/graph.json            generated graph (nodes + edges)

Every note carries taxonomy frontmatter: id, title, type (hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference, enforced by refresh_graph(validate=true)), status (active|draft|deprecated), tags, last_reviewed, optional repo. Notes are linked with typed markdown links — [text](note-id){"type":"…"} — that resolve by id. Legacy [[wiki links]] are rejected by refresh_graph(validate=true).

1. Orient

Start broad, then narrow. Begin with graph_summary, then find hubs using graph_search_nodes(type="hub") and read relevant ones with read_note. Discover repo scopes and tags from the graph rather than assuming a particular folder layout. An external data vault need not contain a root README or framework operational documents.

2. Query the graph

Use the MCP tools directly:

Need	Tool
Repo scopes, tag spellings, most-linked notes	graph_summary
Notes in a repo	graph_search_nodes(repo="<repo>")
Notes of a type	graph_search_nodes(type="policy")
Notes with a tag	graph_search_nodes(tag="<tag>")
Search ids, titles, paths and tags	graph_search_nodes(query="<term>")
Incoming/outgoing links, relationship types and annotations	graph_neighbors(id="<note-id>")

query does not search note bodies. Read candidate notes with read_note and follow their neighbors when metadata search is insufficient. Report any search coverage limits; do not use filesystem or shell searches.

3. Read the source notes

The graph gives ids and paths; the ANSWER lives in the Markdown. Read matched notes with read_note(id="<note-id>") or read_note(path="<vault-relative-path>"). Follow the typed markdown links [text](id){"type":"…"}, resolving each to its node path to pull in related policies, decisions, and repo info. Use each edge's type and annotation to judge which links are worth following; links are the intended navigation, so traverse them rather than guessing.

If the graph looks stale or a path is missing, use refresh_graph. This updates only the generated index; it does not touch Markdown. Do not commit.

4. Answer with citations

• Answer the question directly from what the notes say.
• Cite the backing notes by vault-relative path (e.g. 03_resources/<resource>/index.md) and/or id so the user can verify.
• Distinguish vault facts from inference. If the vault does not cover it, say so plainly — do not invent. Note status: draft/deprecated when relevant.
• For "what links to / relates to X" questions, report the inbound/outbound edges you found, including each edge's relationship type and annotation.