kb-lookup

Matches error text against error_signatures in index.yaml to retrieve knowledge base fixes.

Updated Jun 22, 2026
One-click install
npx skills add https://github.com/ozand/knowledge-base-template --skill kb-lookup-ozand
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: kb-lookup
Source: https://github.com/ozand/knowledge-base-template/tree/main/_template/skills/kb-lookup
Command: npx skills add https://github.com/ozand/knowledge-base-template --skill kb-lookup-ozand

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a command fails or a provider errors, engineers often retry blindly or re-debug issues that were already solved before. This Skill looks up the exact error in a file-based knowledge base of lessons so known fixes are applied immediately instead of being rediscovered. ## Core Features & Use Cases - Signature-Based Matching: Compares the real error text against error_signatures entries in index.yaml using case-insensitive substring matching. - Structured Lesson Retrieval: Loads matched lesson files and presents Symptom, Root Cause, Resolution, and Prevention sections, ordered by severity when multiple lessons match. - Guided Fallback: When no signature matches, it directs the user to capture the new error as a lesson so it is never solved twice. - Use Case: A Pi agent hits a provider authentication error; instead of retrying, it matches the error against the KB index, finds lesson KB-0012, and applies the documented resolution steps. ## Quick Start Ask the agent to look up the current error in the knowledge base before retrying the failed command.

Frequently Asked Questions about kb-lookup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I look up a fix for an error in a knowledge base?▼

Error lookup works by matching the exact error text against error_signatures entries in index.yaml using case-insensitive substring matching. Matched lessons are loaded from their file paths and their resolution and prevention steps are presented.

How does error signature matching work in index.yaml?▼

Each lesson entry in index.yaml contains an error_signatures list of strings. The lookup checks whether any signature appears as a substring in the actual error text, collecting all matching lessons and showing the most severe first.

What happens when no error signature matches?▼

When no signature in index.yaml matches the error text, the lookup reports that no lesson was found and suggests running kb-capture to record the new error as a lesson for future lookups.

Why should I use index.yaml instead of reading lesson files directly?▼

The error_signatures in index.yaml are the authoritative match source, so parsing lesson frontmatter for matching is unnecessary. Reading large files like log.md or index.md during lookup is explicitly avoided to keep lookups fast.

What are the limitations of signature-based error matching?▼

Substring matching only works when the error text contains a known signature, so paraphrased or novel errors will miss. For semantic matching across lessons, the optional QMD module provides a separate kb-search capability.