| name | kb-search |
| description | Search across all KB files in docs/kb/ for a keyword, topic, or tag. Returns matching files and relevant excerpts. |
| disable-model-invocation | true |
Knowledge Base Search
You are a knowledge base search assistant. Your job is to search across the project's KB files for relevant information using content, tags, and cross-references.
Instructions
Step 1: Get Search Query
Check if the user provided a search term after the command (e.g., /kb-search authentication or /kb-search tag:security).
- If a term was provided: Use it as the search query.
- If no term was provided: Use AskUserQuestion to ask:
- Question: "What keyword or topic would you like to search for in the knowledge base?"
- Header: "KB Search"
- Allow free-text input.
Step 2: Parse Query Type
Determine the search mode:
- Tag search: If the query starts with
tag: (e.g., tag:security), search frontmatter tags arrays.
- Content search: Otherwise, search file content, names, and tags.
Step 3: Search KB Files
- Glob for all
.md files under docs/kb/ (excluding docs/kb/README.md).
- If no KB files exist, inform the user: "No KB files found in
docs/kb/. Run /kb-init to set up the knowledge base." and stop.
- For each KB file, read its frontmatter and content.
For tag search:
- Match the query tag against each file's
tags array (case-insensitive).
- Also check
related references for files that link to matching files.
For content search:
- Grep across all found KB files for the search query (case-insensitive).
- Check file names and directory names for matches (e.g., searching "api" should match
docs/kb/api-conventions.md).
- Check frontmatter
tags for matches (a content search for "security" should also surface files tagged security).
Step 4: Search Global Learnings
- Read
docs/kb/_global-learnings.md if it exists (this is the dedicated global learnings KB file).
- Check if any global learning entries match the search query.
- Also check CLAUDE.md for a legacy
### Global Learnings inline section (older KB setups may still have this). If found, search it too.
Step 5: Display Results
Present results grouped by source, including frontmatter metadata:
KB Search Results for: "{query}"
================================
KB Files with matches:
1. docs/kb/api-conventions.md
Tags: [api, rest, conventions]
Related: [[auth]], [[database]]
Last updated: 2026-04-01 | Pinned: No
> Matching excerpt line 1
> Matching excerpt line 2
2. docs/kb/auth/tokens.md
Tags: [auth, security, tokens]
Related: [[api-conventions]]
Last updated: 2026-03-28 | Pinned: Yes
> Matching excerpt
Also related (via cross-references):
3. docs/kb/database.md — related to matched file api-conventions.md
Global Learnings:
> Matching learning entry
Found {count} match(es) across {file_count} file(s).
If no results found:
"No matches found for '{query}' in the knowledge base. The KB currently has {file_count} file(s) with tags: {unique tags list}."
