Knowledge Retrieval Skill

Purpose

Internal-first knowledge retrieval protocol. Each piece of knowledge lives in exactly ONE tier. Search sources in order, stop when sufficient context found.

Three Knowledge Tiers

Rule: Each piece of knowledge lives in exactly ONE tier. Other systems reference it, never copy it.

When Active

• Starting implementation (check for existing patterns)
• Debugging (check for similar findings)
• Making decisions (check for prior ADRs)
• Researching libraries (check for previous evaluations)
• Reviewing code (check for conventions)

Retrieval Chain (5 Levels)

Search sources in order, stop when sufficient context found:

Level 1 Multi-Level Discovery

docs/index.json registries can exist at any level. Discover them all with a single glob, then read each to understand its scope from the description field:

Glob: **/docs/index.json

Use the registry closest to the files being worked on as primary. See references/search-strategy.md for query patterns.

No registry found? Prompt the user:

No docs/index.json found. Run /docs to initialize one. This enables consistent, session-persistent knowledge retrieval for all agents.

Search Protocol

Search sources in order, stop when sufficient context found. See references/search-strategy.md for full retrieval chain, query examples, and source-specific techniques.

Key principle: Start internal (docs/ index — all levels), then RAG, then skills, then codebase grep, then external (Context7/WebSearch). Stop as soon as you have sufficient context.

Decision Matrix

Integration with Existing Skills

docs-seeker

Handles Context7 + WebSearch (Level 5):

docs-seeker → resolve-library-id → get-library-docs
docs-seeker → WebSearch (if Context7 fails)

research

Handles deep multi-source investigation:

research → knowledge-retrieval (internal first)
research → docs-seeker (external)
research → synthesize findings

Cross-Source Bridging

docs/ (L1) and RAG (L2) complement each other. Bridge them:

Rule: Always cross-reference. An ADR without code validation is stale. A code pattern without docs is undocumented risk.

Cross-Platform RAG Coordination

When a query spans platforms, coordinate RAG queries:

Dedup rule: Group results by concept, not file. Note platform differences. Authority rule: Definitions live in design system RAG, usage examples in platform RAG. Prefer the authoritative source.

Staleness Detection

RAG staleness rule: When stale_sidecar: true, use code chunks for implementation details but ignore metadata fields (summary, topics, component_names). Sidecar regeneration is handled server-side automatically.

Best Practices

1. Start internal: Always check docs/index.json first
2. Use agentHint: Match hints against current task for relevance
3. Skip irrelevant levels: No RAG server? Skip L2, go directly to L4 (Grep/Glob codebase search) — never block on RAG availability
4. Stop when sufficient: Don't search all levels unnecessarily
5. Attribute sources: Note where each finding came from
6. Validate staleness: Check dates on knowledge entries
7. Expand keywords: Try synonyms if no results
8. Combine results: Merge complementary findings
9. Update knowledge: If external search yields new insight, capture it

Aspect Files

Related Skills

• knowledge-retrieval/references/knowledge-base.md — Knowledge system structure
• knowledge-capture — Persist new learnings
• docs-seeker — External documentation retrieval
• research — Deep multi-source investigation

References

• references/search-strategy.md — Source-specific search techniques
• references/priority-matrix.md — Decision table for source selection