COG-6311 feat: Add SKILLS search type and skill gate - #4662
Open
Vasilije1990 wants to merge 1 commit into
Open
Conversation
Skills (dataset-scoped SKILL.md playbooks) were invisible outside the
agentic retriever: their embeddings in the Skill_search_text collection
were written on ingest but never searched. This adds procedural-memory
discovery on top of the existing index — no new indexing.
- SearchType.SKILLS: one vector search, no LLM. Requires exactly one
explicit dataset (same invariant as the agentic skill loader) and
filters strictly on dataset_scope + is_active; empty-scope legacy
skills are excluded. Results are metadata-only (name, description,
maintainer, tags, declared tools, score) — procedure bodies stay
behind load_skill / GET /skills/{id} to preserve progressive
disclosure. A missing collection returns [] instead of NoDataError
so skill-less datasets degrade silently.
- Skill gate in recall(): a deterministic weighted-regex gate (no LLM,
no I/O) detects procedural queries and runs a concurrent metadata-only
SKILLS lookup, appending hits tagged source="skills". Additive and
fail-safe; only fires when exactly one dataset is targeted; disable
with SKILL_GATE_ENABLED=false.
- Wiring: retriever registry, result normalization (kind "skill"),
ResponseSkillEntry in the recall response union, CLI --query-type
choice, and the exactly-one-dataset validation in search().
- 36 new unit tests (retriever filtering/projection, gate
classification, recall wiring); README and CLAUDE.md document the
feature.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Skills (dataset-scoped
SKILL.mdplaybooks) are invisible outside the agentic retriever today: their embeddings in theSkill_search_textvector collection are written on every ingest but nothing ever searches them — the only reader is delete cleanup. This PR adds procedural-memory discovery on top of that existing index (no new indexing) plus a deterministic gate that surfaces skills automatically on procedural questions.SearchType.SKILLSSkillsRetriever(aSummariesRetriever-style clone) runs one vector search overSkill_search_text— no LLM call.search()alongside the agentic check, and again at retriever construction). Payloads are filtered ondataset_scopemembership andis_active; empty-scope legacy skills are excluded. Re-ingesting (an upsert) makes legacy skills visible again.procedure/skill_text/search_textare stripped — full bodies stay behind theload_skilltool orGET /skills/{skill_id}, preserving the progressive-disclosure design.[](deliberate divergence from SUMMARIES'NoDataError): "no skills ingested" is a normal state and the gate path must degrade to a no-op.recall(query_type=...), andcognee-cli search --query-type SKILLS.Deterministic skill gate in
recall()cognee/api/v1/recall/skill_gate.py— weighted regexes with the query router's negation suppression; no LLM, no I/O. Procedural phrasing ("how do I…", "steps to…", "runbook", "walk me through…") fires it; a bare ops verb alone does not.When it fires and exactly one dataset is targeted, a metadata-only SKILLS lookup runs concurrently with the main lanes and hits are appended as
ResponseSkillEntrytaggedsource="skills". Additive only — the main answer never waits on it, gate failures are swallowed, explicit SKILLS/AGENTIC queries bypass it, andSKILL_GATE_ENABLED=falseturns it off. The auto-router is untouched (routing to SKILLS would replace answers with listings).Tests
36 new unit tests, all green (retriever scope/active filtering, empty-scope exclusion, over-fetch trim, dedupe, body-stripping projection, sparse legacy payloads, missing collection; gate classification table, negation, env flag; six recall-wiring tests including gate-failure isolation and the single-dataset skip). Affected suites pass: 624 tests across tools/skills-router/recall/retrieval, 118 across search+gate+retriever, 13 CLI search tests.
README and CLAUDE.md document the feature inline.
🤖 Generated with Claude Code