mdsel-skill
Access large Markdown files using declarative selectors via the mdsel CLI
What is mdsel-skill?
mdsel-skill is a Claude Code plugin that enables efficient access to large Markdown files using declarative selectors instead of full-file reads.
Instead of reading entire documentation files and wasting thousands of tokens, agents can select specific sections using simple selectors like h2.0 (first H2 heading) or h3.1 (second H3 heading).
Token Efficiency
Using the Read tool on large Markdown files wastes tokens:
| File Size | Read Tool | mdsel | Savings |
|---|
| 500 words | ~2,000 tokens | ~100 tokens | 95% |
| 2,000 words | ~8,000 tokens | ~100 tokens | 98.75% |
| 5,000 words | ~20,000 tokens | ~100 tokens | 99.5% |
Why mdsel-skill instead of mdsel-mcp?
The older MCP-based approach injected ~600 tokens of tool schema into every conversation. Skills load on-demand, consuming only ~50-100 tokens when inactive—a 96% reduction in overhead.
Features
- Token Efficient: Reduces token usage by 95-99.5% for large Markdown files
- Easy Installation: Install via Claude Code marketplace
- Declarative Selectors: Simple
h2.0, h3.1 syntax for accessing sections
- Automatic Hooks: Optional reminder hooks encourage proper usage patterns
- Zero-Based Indexing: Predictable selector behavior with 0-based indexing
- npx Fallback: Works without global installation using npx
Installation
Claude Code (Marketplace)
# Add the marketplace
/plugin marketplace add dabstractor/mdsel-skill
# Install the plugin
/plugin install mdsel@mdsel-marketplace
# Verify installation
/plugin list
Using mdsel CLI
The skill uses the mdsel CLI tool. Install it separately if not already available:
# Install globally
npm install -g mdsel
# Or use npx without installation
npx mdsel h2.0 README.md
Platform Support
- macOS (darwin): Fully supported
- Linux: Fully supported
- Windows: Not officially supported
Quick Start
# 1. Get the document index (shows all available selectors)
mdsel README.md
# 2. Select specific sections using declarative selectors
mdsel h2.0 README.md # First H2 heading
mdsel h2.1 README.md # Second H2 heading
mdsel h3.0 README.md # First H3 heading
Usage
When to Use mdsel
Use mdsel when:
- File word count exceeds MDSEL_MIN_WORDS (default: 200)
- You need specific sections, not the entire document
- Token efficiency is important
Decision Flow
- File is Markdown (
.md extension)?
- Word count > MDSEL_MIN_WORDS?
- Yes: Use
mdsel <selector> <file> for specific content
- No: Read tool is acceptable
Selector Syntax
mdsel uses 0-based indexing with the pattern <element-type>.<index>.
IMPORTANT: Selectors use 0-based indexing, not 1-based.
h2.0 = First H2 headingh2.1 = Second H2 heading
| Selector | Description | Example |
|---|
h1.0 | First H1 heading | # Title |
h2.0 | First H2 heading | ## Installation |
h2.1 | Second H2 heading | ## Usage |
h3.0 | First H3 heading | ### Quick Start |
h3.2 | Third H3 heading | ### Advanced Usage |
Critical: 0-Based Indexing
Many users expect 1-based indexing—this is the most common error!
File content:
# Main Title (h1.0 - FIRST h1)
## Introduction (h2.0 - FIRST h2)
## Getting Started (h2.1 - SECOND h2)
### Installation (h3.0 - FIRST h3)
### Configuration (h3.1 - SECOND h3)
## API Reference (h2.2 - THIRD h2)
To access "## Introduction", use h2.0, not h2.1.
Examples
Example 1: Basic Selection
# Select the first H2 section
mdsel h2.0 docs/API.md
# Select the third H2 section
mdsel h2.2 docs/API.md
Example 2: Multiple Selections
# Select multiple sections sequentially
mdsel h2.0 README.md # Installation section
mdsel h2.1 README.md # Usage section
mdsel h2.2 README.md # API Reference section
Example 3: Nested Headings
# For a file like:
# # Documentation
# ## Getting Started
# ### Prerequisites
# ### Installation
# ## Configuration
# Select specific nested sections
mdsel h3.0 README.md # First H3 (Prerequisites)
mdsel h3.1 README.md # Second H3 (Installation)
Example 4: Using npx
# Use npx to run mdsel without global installation
npx mdsel h1.0 README.md
npx mdsel h2.0 README.md
