char-index-skill

Character-level index-based string manipulation as a Claude Code Skill.

LLMs generate text token-by-token and struggle with exact character counting. This skill provides precise index-based tools for test code generation, string parsing, and position-critical tasks.

Evolved from char-index-mcp. The MCP server is still supported — see MCP Server section.

Installation

Clone the repository:

git clone https://github.com/agent-hanju/char-index-skill.git

Copy skills/char-index-skill/ into your project's .claude/skills/ directory, or use it directly from the cloned repo.

Usage

Claude will automatically invoke the skill when you need character-level string operations. You can also call it explicitly with /char-index-skill.

All operations are available via:

python ${CLAUDE_SKILL_DIR}/scripts/char_ops.py <command> [options]

See SKILL.md for the full command reference.

Features (12 Operations)

Finding (4)

• find-nth-char - Find nth occurrence of a character
• find-all-chars - Find all indices of a character
• find-nth-substring - Find nth occurrence of a substring
• find-all-substrings - Find all occurrences of a substring

Splitting & Extraction (4)

• split-at - Split string at multiple positions
• extract - Extract substring by range
• extract-between - Extract text between two markers
• extract-batch - Extract multiple substrings by index ranges

Modification (3)

• insert - Insert text at specific position
• delete - Delete characters in range
• replace - Replace range with new text

Utilities (1)

• count - Character statistics (total, letters, digits, etc.)

Quick Examples

# Find 3rd 'l'
python ${CLAUDE_SKILL_DIR}/scripts/char_ops.py find-nth-char \
  --text "hello world" --char "l" --n 3
# {"index": 9}

# Split at positions
python ${CLAUDE_SKILL_DIR}/scripts/char_ops.py split-at \
  --text "hello world" --indices "2,5,8"
# {"parts": ["he", "llo", " wo", "rld"]}

# Extract between markers
python ${CLAUDE_SKILL_DIR}/scripts/char_ops.py extract-between \
  --text "<tag>content</tag>" --start-marker "<tag>" --end-marker "</tag>"
# {"content": "content", ...}

# Count characters
python ${CLAUDE_SKILL_DIR}/scripts/char_ops.py count --text "Hello World!"
# {"total": 12, "letters": 10, "digits": 0, "spaces": 1, "special": 1}

See examples.md for more practical examples.

Key Points

• 0-indexed: All positions start from 0
• 1-based occurrence: find-nth-* uses --n 1 for first occurrence
• Negative indices: -1 = last char, -5 = 5th from end
• Range format: [start, end) - start inclusive, end exclusive
• Unicode safe: Each Unicode character = 1 position
• JSON output: All operations return JSON for easy parsing

Use Cases

1. Test Code Generation - Generate strings with exact character counts
2. Data Processing - Split/extract data at precise positions
3. Text Formatting - Insert/delete/replace at specific indices
4. LLM Response Parsing - Extract content between XML tags by position

Project Structure

char-index-skill/
├── skills/
│   └── char-index-skill/
│       ├── SKILL.md               # Skill definition
│       ├── examples.md            # Usage examples
│       └── scripts/char_ops.py    # Implementation (12 operations)
├── char_index_mcp/                # MCP server (legacy)
│   ├── server.py
│   ├── char_ops.py                # Synced copy
│   └── tests/
├── pyproject.toml                 # MCP package config
├── README.md
└── LICENSE

Development

git clone https://github.com/agent-hanju/char-index-skill.git
cd char-index-skill

python -m venv .venv
.venv/Scripts/activate  # or source .venv/bin/activate

pip install -e .
pytest char_index_mcp/tests/ -v
ruff check .
mypy char_index_mcp/

MCP Server (Legacy)

The char-index-mcp package provides the same 12 operations as an MCP server for integration with Claude Desktop, Cursor, and other MCP clients. This is maintained for backward compatibility but the Claude Code Skill is the recommended approach.

# Install
pip install char-index-mcp

# Or run directly
uvx char-index-mcp

Configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "char-index": {
      "command": "uvx",
      "args": ["char-index-mcp"]
    }
  }
}

License

MIT License - see LICENSE file for details