agentsope/SkillAlchemy / skills/agentsop-multiscale-chunking
agentsop-multiscale-chunking
VerifiedDesigns multiscale chunking for RAG by embedding small units for retrieval precision and returning larger context for synthesis. Use when fixed-size chunks either lose surrounding context or dilute relevance in long documents, manuals, filings, or codebases. Covers sentence-window and parent-child or auto-merging strategies, base chunk sizing, and evaluation. Do not use when a single chunk scale already meets retrieval and generation needs.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.9 KB |
| SKILL.md | skill md | 19.5 KB |
| intermediate/operation_candidates.json | config | 6.2 KB |
| references/R1-source-evidence.md | markdown | 7.3 KB |
intermediate/operation_candidates.json
View on GitHub{
"skill": "multiscale-chunking",
"version": "0.1.0",
"type": "enhancement-overlay",
"overlay_id": "C5",
"base_skill": "llamaindex",
"refines": ["llamaindex:OP-02", "llamaindex:OP-05"],
"core_flip": "Decouple the embed-unit from the return-unit: embed small for retrieval precision, return large for generation context.",
"operation_candidates": [
{
"id": "MSC-01",
"name": "ChunkSizeSweep",
"trigger": "New long-doc corpus; chunk size unknown; before any multi-scale work",
"action": "Generate ~20 QA pairs; sweep chunk_size in {128,256,512,1024,2048} with overlap 10-20%; build one VectorStoreIndex per config; record faithfulness + relevancy + p95 latency",
"output": "A pinned single winner, OR a documented non-flat frontier that authorizes multi-scale chunking",
"evidence": "llamaindex.ai/blog/evaluating-the-ideal-chunk-size-for-a-rag-system-using-llamaindex-6207e5d3fec5 ; llamaindex:OP-02"
},
{
"id": "MSC-02",
"name": "SentenceWindowSetup",
"geometry": "horizontal",
"trigger": "Flat prose; point-facts needing surrounding paragraph; lowest setup cost wanted",
"action": "SentenceWindowNodeParser(window_size=3) embeds single sentences with N-neighbor windows in metadata; at query time apply MetadataReplacementPostProcessor(target_metadata_key='window') so the LLM receives the window, not the lone sentence",
"output": "Sentence-level matching precision + paragraph-level synthesis context",
"evidence": "developers.llamaindex.ai SentenceWindow / MetadataReplacement docs ; llamaindex R3 Dilemma 5"
},
{
"id": "MSC-03",
"name": "AutoMergingHierarchy",
"geometry": "vertical",
"trigger": "Documents with clear hierarchy; bursty multi-chunk relevance",
"action": "HierarchicalNodeParser.from_defaults(chunk_sizes=[2048,512,128]) builds leaf->parent->root tree; index leaf nodes in a VectorStoreIndex, keep all nodes in a docstore; retrieve with AutoMergingRetriever which returns the parent once a configured fraction of its children are in the hit set",
"output": "Leaf-level precision escalating to section-level context when warranted",
"evidence": "developers.llamaindex.ai/python/framework/integrations/retrievers/auto_merging_retriever/ ; llamaindex:OP-05"
},
{
"id": "MSC-04",
"name": "WindowVsMergeChoice",
"trigger": "Multi-scale authorized (MSC-01 non-flat) but strategy undecided",
"action": "Inspect document structure: flat -> MSC-02; structured/bursty -> MSC-03; unknown -> start MSC-02 (cheaper) and escalate to MSC-03 if multi-chunk queries underperform",
"output": "A strategy chosen by document shape, not by elegance",
"evidence": "llamaindex R3 Dilemma 5 ; medium.com/@harsh_77214/beyond-naive-rag-comparing-basic-sentence-window-and-auto-merging-retrieval-..."
},
{
"id": "MSC-05",
"name": "EmbedReturnDecouple",
"trigger": "Any time chunk-size tuning oscillates between precision and context",
"action": "Set embed-unit small, return-unit large; never let them be the same object once the sweep is non-flat; verify by inspecting what text the retriever actually sends to the synthesizer (must be the large unit)",
"output": "Pareto improvement on precision x context that no single chunk size achieves",
"evidence": "llamaindex Principle 2 (Node relationships) ; llamaindex R3 Dilemma 1 resolution"
},
{
"id": "MSC-06",
"name": "MetadataBudgetGuard",
"trigger": "Small embed-units (<=256 tokens) with rich metadata propagated into payload",
"action": "Ensure metadata never occupies >50% of the embed-unit token budget; strip/shorten metadata before shrinking chunks",
"output": "Embed-units carry signal, not mostly boilerplate metadata",
"evidence": "github.com/run-llama/llama_index/issues/12200 ; #13792 ; llamaindex A7"
},
{
"id": "MSC-07",
"name": "MeasureOrRevert",
"trigger": "Multi-scale config wired but lift unverified",
"action": "Re-run the Gate-0 eval set; require a measurable faithfulness lift over the best single chunk size; if none, revert to the pinned single size",
"output": "Evidence that the added complexity earns its keep, or its removal",
"evidence": "llamaindex Stage 2 (eval loop gates every change)"
}
],
"dilemmas": [
{
"id": "D5.1",
"title": "Sentence-Window vs Auto-Merging",
"resolution": "Match expansion geometry to document structure: flat prose -> horizontal (sentence-window); clear hierarchy or bursty multi-chunk -> vertical (auto-merging); unknown -> start sentence-window (lower setup cost)",
"ops": ["MSC-02", "MSC-03", "MSC-04"]
},
{
"id": "D5.2",
"title": "Chunk-size sweep: the 1024 optimum and when it does not converge",
"resolution": "Sweep first; Uber 10-K peaked at 1024 (prose default; code 80-160). If the frontier is non-flat, do not compromise on a middle size -> decouple via MSC-05",
"ops": ["MSC-01", "MSC-05", "MSC-06"]
}
],
"anti_patterns": [
"A1: bump chunk_size (e.g. 4096) when answers feel incomplete -> decouple instead",
"A2: SentenceWindowNodeParser without MetadataReplacementPostProcessor",
"A3: index parent nodes for auto-merging -> index leaves, store parents",
"A4: pick a compromise chunk size on a non-flat frontier",
"A5: multi-scale on a short/static corpus (<100k tokens)",
"A6: ship multi-scale config without re-running the eval set",
"A7: shrink embed-unit while metadata dominates the payload"
],
"boundaries": [
"B1: short/static corpus (<100k tokens) -> prompt-stuff with caching",
"B2: chunk-size sweep already converged -> pin and stop",
"B3: bottleneck is embedding/reranker/synthesizer, not precision-vs-context",
"B4: hard real-time (<100ms) retrieval -> docstore lookups add latency"
],
"cross_framework": {
"horizontal_sentence_window": {
"llamaindex": "SentenceWindowNodeParser + MetadataReplacementPostProcessor",
"langchain": "no first-class equivalent"
},
"vertical_parent_child": {
"llamaindex": "HierarchicalNodeParser + AutoMergingRetriever",
"langchain": "ParentDocumentRetriever"
}
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |