agentsop-multiscale-chunking
Enhancement-overlay (C5) for RAG over long documents — the chunk-paradox resolution. Activate when a single fixed chunk size cannot satisfy both retrieval precision (small chunks) and generation context (large chunks): small chunks lose surrounding context, large chunks dilute embedding relevance into "topic averages". Encodes the core flip — decouple the embed-unit from the return-unit: embed small for retrieval precision, return large for synthesis context — and the SOP to pick a base chunk size, choose a horizontal (sentence-window) vs vertical (auto-merging / parent-child) expansion strate
npx skills add agentsope/SkillAlchemy --skill agentsop-multiscale-chunking --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Enhancement overlay that provides a recipe for resolving the chunk paradox in RAG over long documents. It instructs when to activate, and which two expansion strategies to use (Sentence-Window for horizontal growth and Auto-Merging for vertical growth). It specifies a protocol to pick a base chunk size, perform a chunk-size sweep, and then decide between horizontal or vertical expansion based on document structure and evaluation results. It defines concrete actions to decouple embed-unit from return-unit so retrieval remains precise while generation retains context. It includes procedures to measure lift via Gate-0, Gate-1, and Gate-2, and to pin a chosen configuration into index metadata. It also describes how to implement either SentenceWindowNodeParser with a MetadataReplacementPostProcessor for horizontal expansion or HierarchicalNodeParser and AutoMergingRetriever for vertical expansion, along with supporting tooling references and anti-patterns.
How it works
The skill provides a three-gate workflow:
- Gate 0: run a chunk-size sweep over {128,256,512,1024,2048} with overlap, evaluating faithfulness, relevancy, and latency; pin a single winner or proceed if non-flat frontier.
- Gate 1: choose expansion strategy by document structure: Flat prose favors Sentence-Window (horizontal); clear hierarchy or bursty relevance favors Auto-Merging (vertical).
- Gate 2: wire and measure lift by re-running the same eval set; pin chosen parser/retriever config and embedding model, or revert if no lift is observed.
Operational components include:
- MSC-01 MSC-05 MSC-06 for multi-scale tuning, core flip, and metadata budget guard.
- MSC-02 (SentenceWindowSetup): uses SentenceWindowNodeParser(window_size=3) and MetadataReplacementPostProcessor to ensure the window is delivered to the LLM.
- MSC-03 (AutoMergingHierarchy): uses HierarchicalNodeParser.from_defaults with a leaf→parent→root tree, and AutoMergingRetriever.
- MSC-04 (WindowVsMergeChoice): decides between MSC-02 or MSC-03 based on document shape.
- MSC-05 (EmbedReturnDecouple): enforces embed small and return large units once the sweep is non-flat.
The protocol also specifies anti-patterns and boundaries to avoid common misconfigurations, and cross-references external docs for deeper details.
When to use it
Activate when a single fixed chunk size cannot satisfy both retrieval precision (small chunks) and generation context (large chunks), i.e., when a chunk-size sweep stalls and the frontier is non-flat with faithfulness or relevancy plateauing. It should be used for long prose, manuals, filings, or codebases where chunk-paradox-resolution is needed.
What it can touch
The workflow touches tools and components such as:
SentenceWindowNodeParserandMetadataReplacementPostProcessorfor horizontal expansion.HierarchicalNodeParser.from_defaults(chunk_sizes=[2048,512,128])andAutoMergingRetrieverfor vertical expansion.- Evaluation utilities from llama_index to compute faithfulness, relevancy, and latency.
- It references external docs and code paths like [[llamaindex]] OP-02/OP-05 and related implementations.
Caveats
It requires maintaining a clear gate-driven process; if no lift is observed after Gate 2, revert to the pinned single-size configuration. It assumes availability of multi-scale capable retrievers and parsers, and relies on embedding-model behavior and docstructure signals to select between expansions.
# Multi-scale Chunking · C5 Enhancement Overlay > Overlay on top of [[llamaindex]]. The base skill teaches the 5-layer RAG > pipeline and lists `DecoupleChunkScope` as one optimization knob among many. > This overlay zooms in on that single knob and turns it into a standalone > recipe: **how to resolve the chunk paradox when one chunk size is provably > not enough.** Third-person analytical view for an agent writing / reviewing > RAG ingestion code — not an end-user tutorial. --- ## 1. 何时激活 (Activation Rules) Activate this overlay when **all three** RAG preconditions hold and the chunk paradox has actually surfaced: 1. The corpus is **long documents** — prose manuals, financial filings, legal contracts, research papers, codebases — where a single answer-bearing fact sits inside a larger context that the LLM needs to interpret it. 2. A **chunk-size sweep has stalled**: small chunks (128–256) win retrieval precision but the LLM answers from fragments; large chunks (1024–2048) give rich context but recall on specific queries drops because the embedding becomes a "topic average". The official failure-mode checklist documents both poles as *separate* failures — #2 (wrong chunk from too-
- 1. 何时激活 (Activation Rules)
- 2. 核心心智模型 (Core Mental Model)
- 3. SOP 工作流 (Decision Protocol)
- Gate 0 — Pick the base chunk size first (and try to stop here)
- Gate 1 — Choose the expansion strategy by document structure
- Gate 2 — Wire it and measure the lift
- 4. 操作模型 (Operation Models)
- MSC-01 — ChunkSizeSweep
- MSC-02 — SentenceWindowSetup (horizontal expansion)
- MSC-03 — AutoMergingHierarchy (vertical expansion)
- MSC-04 — WindowVsMergeChoice
- MSC-05 — EmbedReturnDecouple (the core flip)
- MSC-06 — MetadataBudgetGuard
- MSC-07 — MeasureOrRevert
What does the agentsop-multiscale-chunking skill do?
Enhancement-overlay (C5) for RAG over long documents — the chunk-paradox resolution. Activate when a single fixed chunk size cannot satisfy both retrieval precision (small chunks) and generation context (large chunks): small chunks lose surrounding context, large chunks dilute embedding relevance into "topic averages". Encodes the core flip — decouple the embed-unit from the return-unit: embed small for retrieval precision, return large for synthesis context — and the SOP to pick a base chunk size, choose a horizontal (sentence-window) vs vertical (auto-merging / parent-child) expansion strate
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-multiscale-chunking --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.