playbooks

home / skills / zpankz / mcp-skillset / cli-router

cli-router skill

/cli-router

This skill routes tasks to the most suitable locally installed CLI tool using semantic intent matching and routing logic.

npx playbooks add skill zpankz/mcp-skillset --skill cli-router

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.4 KB
---
name: cli-router
description: Routes tasks to locally installed CLI tools using semantic matching. Triggers on tasks requiring shell commands, file operations, code search, data processing, visualization, or external tool invocation. Uses cli-index for semantic routing.
---

# CLI Router

Routes tasks to the most appropriate CLI tool based on semantic intent matching.

## Trigger Conditions

Activate when task involves:
- Shell/terminal operations
- File search or navigation
- Code search (semantic or pattern)
- Data processing (CSV, JSON)
- Visualization generation
- External tool invocation

## CLI Categories

| Category | Tools | Triggers |
|:---------|:------|:---------|
| **ai_llm** | claude, gemini, codex, amp, aider | AI help, implement, explain |
| **semantic_search** | ck, ast-grep, osgrep | semantic search, find code, pattern |
| **knowledge_graph** | cypher-shell, turbovault | graph, neo4j, knowledge |
| **data_processing** | qsv, csvtk, nu, jq | csv, json, transform, data |
| **file_navigation** | yazi, broot, fd, rg | browse, find files, navigate |
| **code_quality** | bat, difftastic, delta | diff, syntax, format |
| **visualization** | d2, mermaid, mermaid-ascii | diagram, flowchart, visual |
| **mcp_tools** | mcp-skillset, lootbox, automcp | mcp, skills, tools |
| **productivity** | fabric, atuin, btop, zellij | patterns, history, monitor |
| **document** | docling, pdf-search, qmd | pdf, document, markdown |

## Routing Logic

```bash
# Use cli-index for semantic routing
cli-index route "{user_intent}"

# Example output:
# tool: ck
# category: semantic_search
# confidence: 0.85
# command_hint: ck --sem "async functions" src/
```

## Decision Tree

```
CLI Task Detected
    │
    ├── Code search?
    │   ├── Semantic? → ck --sem
    │   ├── Pattern/AST? → ast-grep
    │   └── Grep-like? → rg
    │
    ├── File operations?
    │   ├── Navigate? → yazi | broot
    │   ├── Find files? → fd
    │   └── Search content? → rg
    │
    ├── Data processing?
    │   ├── CSV? → qsv | csvtk
    │   ├── JSON? → jq | sj
    │   └── Structured? → nu
    │
    ├── Visualization?
    │   ├── Diagrams? → d2
    │   ├── Flowcharts? → mermaid
    │   └── ASCII? → mermaid-ascii
    │
    ├── AI assistance?
    │   ├── Claude preferred? → claude
    │   ├── Long context? → gemini
    │   └── OpenAI? → codex
    │
    └── Document processing?
        ├── PDF? → docling | pdf-search
        └── Markdown? → qmd
```

## Commands

```bash
# Search for matching tools
cli-index search "semantic code search"

# Route to best tool
cli-index route "find async functions in codebase"

# List tools by category
cli-index list semantic_search

# Get tool info
cli-index info ck

# Suggest tool chain
cli-index suggest "search code then visualize dependencies"

# Verify all tools available
cli-index verify
```

## Integration

- **cli-index**: Primary routing CLI
- **ck**: Semantic code search with embeddings
- **reasoning-index**: Command framework routing
- **mcp-skillset**: Skill discovery

## Quick Reference

```yaml
semantic_search: ck --sem "query" path/
pattern_search: ast-grep -p "pattern"
file_find: fd "pattern"
content_search: rg "pattern"
csv_process: qsv [cmd] file.csv
json_query: jq ".path" file.json
diagram: d2 input.d2 output.svg
ai_help: claude -p "query"
```

Overview

This skill routes tasks to the most appropriate locally installed CLI tool using semantic intent matching. It triggers when a task requires shell commands, file or code search, data processing, visualization, or invoking external tools. The router uses cli-index to map natural-language intent to a best-fit CLI, returning a tool, category, confidence, and a command hint. It speeds up command discovery and reduces guesswork when working in terminal-heavy workflows.

How this skill works

When given a user intent, the skill calls cli-index to semantically search and route to the best CLI tool. The response includes the selected tool, category, confidence score, and a suggested command hint (e.g., ck --sem "async functions" src/). Routing follows a decision tree that distinguishes code search, file operations, data processing, visualizations, AI assistance, and document tasks. It can also suggest multi-step tool chains and verify tool availability.

When to use it

  • You need to find code by meaning or pattern across a repository.
  • You want to run data transforms or queries on CSV/JSON files from the shell.
  • You need to navigate, browse, or search files quickly in a large project.
  • You plan to generate diagrams, flowcharts, or ASCII visuals from text.
  • You want the best local CLI for AI assistance or external tool invocation.

Best practices

  • Provide concise, specific intent (include file types, paths, or desired output).
  • Prefer semantic phrases for meaning-based searches and keywords for pattern searches.
  • Verify the suggested command locally before running in production directories.
  • Chain suggestions when tasks require search → transform → visualize steps.
  • Use cli-index verify to confirm required CLIs are installed before execution.

Example use cases

  • Route ‘find async functions in codebase’ to a semantic code search tool with a ck command hint.
  • Detect a CSV aggregation need and recommend qsv or csvtk with concrete flags.
  • Suggest fd or broot for fast file discovery and provide a sample find command.
  • Map ‘generate architecture diagram’ to d2 or mermaid with input/output command hints.
  • Recommend claude or gemini for complex AI-based code explanation tasks and provide the invocation pattern.

FAQ

How reliable are the routing suggestions?

Routing uses semantic matching and returns a confidence score; treat low-confidence suggestions as starting points and validate commands before running.

Can it suggest multi-step tool chains?

Yes—cli-index can propose chained steps (search → transform → visualize) and provide command hints for each stage.

What if a recommended tool is not installed?

Run cli-index verify to check availability. If missing, install the tool or choose an alternative suggested by the router.