# Contextual Chunk Enrichment

> Use this skill when chunks have ambiguous referents that hurt retrieval — for example, a paragraph starting "It supports up to 10,000 connections" where "it" is whatever the document is about. The technique prepends an LLM-generated context block to each chunk before embedding, so the chunk embeds in the right region of vector space.

- Skill: `allanwessels/contextual-chunk-enrichment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add allanwessels/contextual-chunk-enrichment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/allanwessels/contextual-chunk-enrichment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: AllanWessels (https://skillmd.com/u/allanwessels)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/allanwessels/contextual-chunk-enrichment

---


# Contextual Chunk Enrichment

Popularized by Anthropic in 2024. The original chunk often lacks the
context needed to be retrievable on its own. The fix: use an LLM to
prepend a short context block to each chunk before embedding.

## When to use

Use this skill when failure analysis shows:
- Chunks that semantically should be retrievable but aren't
- High retrieval recall on questions that use the chunk's own
  terminology, but low recall on questions that reference the chunk's
  topic by name (where the chunk doesn't repeat that name)
- Documents with strong hierarchical structure where individual
  chunks lose their parent's identity

It's a heavy technique — every chunk needs an extra LLM call at
indexing time — so don't apply it preemptively.

## Procedure

For each chunk during indexing:

1. Take the chunk's text and a window of surrounding context (the
   parent document, or the parent section if the doc is huge).

2. Prompt a small fast LLM:
   ```
   Here is a document:
   <document>
   {whole_doc_or_section}
   </document>

   Here is a chunk from it:
   <chunk>
   {chunk_text}
   </chunk>

   Write a short context block (50-100 tokens) that situates the
   chunk in the document. Identify what it's about, what section it
   comes from, and any referents the chunk uses without defining.
   Do not summarize the chunk's content; you are situating it.
   ```

3. Concatenate the context block + the original chunk text. Embed the
   concatenation, store the original chunk text (without the context
   block) for the LLM to read at query time.

## Why it works

A chunk reading "It supports up to 10,000 concurrent connections"
embeds poorly because "it" is ambiguous; the vector lands somewhere
generic. Prepending "This chunk is from the load balancer
documentation, in the performance limits section. It describes
connection limits." gives the embedding model enough to land near
other load-balancer chunks, where load-balancer questions also land.

The trick is that the LLM at generation time sees only the original
chunk (not the enrichment), so the context window stays clean. The
enrichment only exists in the vector store.

## Cost considerations

- An LLM call per chunk at indexing time. With ~100,000 chunks, that's
  100,000 small LLM calls. Use prompt caching aggressively — the
  document body changes once per chunk, but the system prompt and the
  chunk-extraction logic don't.
- Indexing time goes from minutes to tens of minutes for a typical
  corpus. Acceptable for periodic re-indexing, expensive for live
  ingestion.
- Use a cheap model (Haiku-tier). The task is narrow.

## When NOT to use

- The corpus is already self-contained (each chunk has its own
  headings, parent references inline)
- You're early in tuning — try cheaper retrieval improvements (hybrid,
  reranker) before reaching for this
- Embedding model context limits are tight enough that adding
  enrichment crowds out the chunk's own content