Kb Search Agent Skill

Knowledge Base Search

When to Use

• Looking up Azure SDK design guidelines for a specific language
• Finding examples (good or bad) related to an API pattern
• Retrieving specific knowledge base items by ID
• Understanding what RAG context the AI reviewer sees for a given query
• Investigating what guidance exists for a topic (e.g. naming, async, pagination)

How It Works

The knowledge base contains three entity types linked in a graph:

• Guidelines — Azure SDK design rules (e.g. "Methods returning collections should use paging")
• Examples — Good/bad code snippets linked to guidelines
• Memories — Lessons learned from reviewer feedback, linked to guidelines and examples

A search query hits the Azure AI Search index (semantic + vector search), then resolves all linked entities from Cosmos DB via breadth-first traversal. The result is the same RAG context the AI reviewer would see.

Defaults

Unless the user says otherwise, always apply these defaults:

• Language: Required for all non---ids queries (both --text and --path). Use the language the user is asking about.
• Output: Use --markdown for text/path queries (easier for the agent to read and summarize). --markdown is not allowed with --ids.
• Query mode: Use --text for natural language queries. Use --path to search from a file. Use --ids only when the user provides specific knowledge base IDs.

Three Query Modes

1. Text Search (--text)

Requires --language. Searches the index semantically and returns linked guidelines, examples, and memories.

python cli.py kb search -l <language> --text "<query>" --markdown

2. File Search (--path)

Requires --language. Reads query text from a file and searches the index.

python cli.py kb search -l <language> --path <file> --markdown

3. ID Lookup (--ids)

Retrieves specific items by ID. No other flags allowed (no --language, --text, --markdown, --path).

python cli.py kb search --ids <id1> <id2> ...

Running the Command

Run directly in a foreground terminal with a 60-second timeout (timeout: 60000). By default, let the terminal capture the output so the agent can read it directly. If the output appears truncated (terminal truncates at ~60 KB), re-run with redirection to a file and read it back:

python cli.py kb search -l <language> --text "<query>" --markdown | Out-File -Encoding UTF8 scratch/kb_output.md

Do not use > — it produces UTF-16 in PowerShell 5.1. Always use | Out-File -Encoding UTF8.

Then use read_file on scratch/kb_output.md to get the full results.

Text search:

python cli.py kb search -l <language> --text "<query>" --markdown

File search:

python cli.py kb search -l <language> --path <file> --markdown

ID lookup:

python cli.py kb search --ids <id1> <id2>

After the command completes, read the terminal output and summarize the findings for the user.

Examples

# Search Python guidelines about async
python cli.py kb search -l python --text "async client methods" --markdown

# Search TypeScript guidelines about naming
python cli.py kb search -l typescript --text "method naming conventions" --markdown

# Search Java guidelines about pagination
python cli.py kb search -l java --text "pagination list operations" --markdown

# Retrieve specific items by ID
python cli.py kb search --ids guideline-abc123 example-def456

# JSON output instead of markdown (for structured processing)
python cli.py kb search -l dotnet --text "dispose pattern"

Available Flags

| Flag | Type | Default | Description |

|------|------|---------|-------------|

| --text | string | — | Natural language search query (mutually exclusive with --path) |

| --path | string | — | Path to a file containing query text or code (mutually exclusive with --text) |

| --ids | list | — | One or more knowledge base item IDs to retrieve directly (no other flags allowed) |

| --language / -l | string | — | Language to search (required for all non---ids queries) |

| --markdown | flag | off | Render output as markdown instead of JSON (not allowed with --ids) |

Understanding the Output

Markdown Format (--markdown)

Each result is rendered as a section with:

• Metadata block: {kind}_id (e.g. guideline_id or memory_id), score (if available), and exception status (if true)
• Title: The guideline or memory title
• Content: The full guideline or memory text
• Examples: Good and bad code examples in fenced code blocks

This is the same format the AI reviewer sees during RAG-based reviews.

JSON Format (default)

Returns the full Context object with nested guidelines, examples, and memories including scores and all linked entities. Useful for programmatic inspection.

ID Lookup Format

Returns SearchItem objects as a JSON array with a curated projection of index fields: id, kind, title, content, language, service, is_exception, example_type, and search scores.

Gotchas

• --ids is exclusive: When using --ids, do not pass --language, --text, --markdown, or --path. The command will error.
• --language is required for all non---ids queries: Both --text and --path require --language to filter the index.
• Exactly one of --text or --path: For non-ID queries, provide one but not both.
• Use python cli.py not avc/avc.bat: The wrapper scripts (avc on Linux/macOS, avc.bat on Windows) invoke the system python/python3, which may not be the correct virtual environment. Run python cli.py directly to ensure the right interpreter is used.
• Do NOT use 2>&1: This merges stderr log messages into the output, corrupting it.
• Prefer --markdown for text/path queries: The markdown output is more readable and is what the AI reviewer actually sees. Use JSON only when you need structured data.
• Scores are normalized: Search result scores use Z-score normalization (mean=50). Higher is more relevant.