# Chunking Advisor

> A Claude skill from floflo777/claude-rag-skills.

- **Type:** Skill
- **Install:** `agentstack add skill-floflo777-claude-rag-skills-chunking-advisor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [floflo777](https://agentstack.voostack.com/s/floflo777)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [floflo777](https://github.com/floflo777)
- **Source:** https://github.com/floflo777/claude-rag-skills/tree/main/chunking-advisor

## Install

```sh
agentstack add skill-floflo777-claude-rag-skills-chunking-advisor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```python
# 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

```python
# 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**
```python
# 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](https://github.com/floflo777)
- **Source:** [floflo777/claude-rag-skills](https://github.com/floflo777/claude-rag-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-floflo777-claude-rag-skills-chunking-advisor
- Seller: https://agentstack.voostack.com/s/floflo777
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.