mdsel-marketplace

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

1. File is Markdown (.md extension)?
2. Word count > MDSEL_MIN_WORDS?
3. Yes: Use mdsel <selector> <file> for specific content
4. 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 heading
• h2.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