Chunking Advisor

Chunking Advisor Skill

Analyze your documents and recommend optimal chunking strategies based on content type, use case, and embedding model.

When to Use

Use /chunking-advisor when:

• Setting up a new RAG pipeline and unsure about chunk configuration
• Experiencing poor retrieval quality (chunks too big or small)
• Working with diverse document types (PDFs, code, tables, etc.)
• Optimizing an existing chunking strategy

Chunking Strategy Decision Tree

What type of content?
│
├── Technical Documentation / Code
│   └── Use: Semantic chunking by function/class/section
│       Chunk size: 500-1000 tokens
│       Overlap: 50-100 tokens
│
├── Legal / Contracts
│   └── Use: Hierarchical chunking (clause → section → document)
│       Chunk size: 300-500 tokens
│       Overlap: 100-150 tokens (preserve clause boundaries)
│
├── Product Catalogs
│   └── Use: Fixed per-product chunks
│       Chunk size: One product = one chunk
│       Overlap: None (products are atomic)
│
├── FAQ / Q&A
│   └── Use: Question-answer pairs as chunks
│       Chunk size: Variable (complete Q&A)
│       Overlap: None
│
├── Long-form Articles / Blog Posts
│   └── Use: Semantic chunking by paragraph/section
│       Chunk size: 800-1200 tokens
│       Overlap: 100-200 tokens
│
├── Tables / Structured Data
│   └── Use: Row-based or section-based chunking
│       Preserve headers in each chunk
│       Chunk size: 10-50 rows per chunk
│
└── Mixed Content
    └── Use: Document-aware chunking
        Different strategies per section type
        Maintain parent-child relationships

Chunking Strategies Explained

1. Fixed-Size Chunking

Best for: Homogeneous content, quick implementation Pros: Simple, predictable Cons: May split sentences/paragraphs awkwardly

# Implementation
from langchain.text_splitter import CharacterTextSplitter

splitter = CharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=150,
    separator="\n\n"  # Prefer paragraph breaks
)
chunks = splitter.split_text(document)

Recommended settings by embedding model: | Model | Optimal Chunk Size | Max Chunk Size | |-------|-------------------|----------------| | text-embedding-3-small | 500-800 tokens | 8191 tokens | | text-embedding-3-large | 800-1200 tokens | 8191 tokens | | voyage-2 | 500-1000 tokens | 4096 tokens | | Cohere embed-v3 | 300-500 tokens | 512 tokens |

2. Semantic Chunking

Best for: Technical docs, articles, varied content Pros: Respects content boundaries, better retrieval Cons: More complex, requires NLP

# Implementation using sentence boundaries
from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=150,
    separators=["\n\n", "\n", ". ", "! ", "? ", ", ", " ", ""]
)
chunks = splitter.split_text(document)

Advanced: Embedding-based semantic chunking

# Split when semantic similarity drops
from sentence_transformers import SentenceTransformer
import numpy as np

def semantic_chunk(sentences, model, threshold=0.5):
    embeddings = model.encode(sentences)
    chunks = []
    current_chunk = [sentences[0]]

    for i in range(1, len(sentences)):
        similarity = np.dot(embeddings[i], embeddings[i-1])
        if similarity  int:
    """
    Calculate recommended overlap based on chunk size and content.
    """
    overlap_ratios = {
        "technical": 0.15,  # 15% - preserve code context
        "legal": 0.20,      # 20% - preserve clause boundaries
        "narrative": 0.10,  # 10% - prose flows naturally
        "tabular": 0.0,     # 0% - tables are atomic
        "default": 0.12     # 12% - balanced
    }

    ratio = overlap_ratios.get(content_type, overlap_ratios["default"])
    return int(chunk_size * ratio)

Reference Resources

For detailed chunking guidance:

• Chunking strategies overview: https://app.ailog.fr/en/blog/guides/chunking-strategies
• Semantic chunking: https://app.ailog.fr/en/blog/guides/semantic-chunking
• Hierarchical chunking: https://app.ailog.fr/en/blog/guides/hierarchical-chunking
• Fixed-size chunking: https://app.ailog.fr/en/blog/guides/fixed-size-chunking
• Parent document retrieval: https://app.ailog.fr/en/blog/guides/parent-document-retrieval

Quick Reference Card

| Document Type | Strategy | Size | Overlap | Key Consideration | |---------------|----------|------|---------|-------------------| | Code | By function/class | 500-1000 | 50-100 | Preserve syntax | | Legal | Hierarchical | 300-500 | 100-150 | Clause boundaries | | FAQ | Q&A pairs | Variable | 0 | Complete pairs | | Articles | Semantic | 800-1200 | 100-200 | Paragraph integrity | | Tables | Row-based | 10-50 rows | 0 + headers | Include headers | | Manuals | Section-based | 600-1000 | 100 | Step integrity | | Chat logs | By conversation | Variable | 0 | Timestamp groups |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: floflo777
• Source: floflo777/claude-rag-skills
• License: MIT

Install and usage instructions live in the source repository linked above.