which-tool skill

---
name: which-tool
description: This skill should be used when choosing CLI tools, a tool seems slow, or when "best tool", "which tool", or "tool alternatives" are mentioned.
metadata:
  version: "1.0.0"
---

# Use the Best Tool

Select optimal CLI tools → graceful fallback → research when needed.

<when_to_use>

- Choosing which tool for file search, content search, JSON processing
- Tool taking unexpectedly long for task size
- User expresses frustration with current tool
- Task could be done more elegantly
- Need to verify tool availability before recommending

NOT for: tasks where tool choice is predetermined, simple one-line commands

</when_to_use>

<detection>

Run detection script before selecting tools:

```bash
bun /Users/mg/Developer/outfitter/agents/outfitter/skills/which-tool/scripts/index.ts
```

Parse output to determine:
- Available modern tools
- Missing tools that could enhance workflow
- System context (OS, package managers)

Cache results per session — no need to re-run unless tool availability changes.

</detection>

<selection>

Map task to best available tool:

| Task | Preferred | Fallback | Legacy | Notes |
|------|-----------|----------|--------|-------|
| Find files by name | `fd` | - | `find` | fd: faster, better defaults |
| Search file contents | `rg` | - | `grep` | rg: respects .gitignore, faster |
| AST-aware code search | `sg` | `rg` | `grep` | sg: structure-aware queries |
| Process JSON | `jq` | - | `python`/`node` | jq: domain-specific language |
| View file with syntax | `bat` | - | `cat` | bat: syntax highlighting, git diff |
| List directory | `eza` | - | `ls` | eza: modern output, icons |
| View git diff | `delta` | - | `git diff` | delta: side-by-side, syntax highlighting |
| Navigate directories | `zoxide` | - | `cd` | zoxide: frecency-based jumping |
| Fuzzy select | `fzf` | - | - | fzf: interactive filtering |
| HTTP requests | `httpie` | - | `curl` | httpie: human-friendly syntax |

Selection algorithm:
1. Check detection results for preferred tool
2. If available → use with optimal flags
3. If unavailable → check fallback column
4. If no fallback → use legacy with best-effort flags
5. Note gap if preferred tool would significantly improve workflow

</selection>

<fallback>

When preferred tool unavailable:

**Minor improvement** (preferred 10–30% better):
- Use next best option silently
- Don't interrupt workflow

**Significant improvement** (preferred 2x+ better):
- Use fallback
- Surface suggestion: `◇ Alternative: {TOOL} would be {BENEFIT} — install with {COMMAND}`
- Continue without blocking

**Critical gap** (task extremely tedious with fallback):
- Surface suggestion: `◆ Caution: {TOOL} recommended for this task — {FALLBACK} will be slow/limited`
- Offer choice: install now, proceed anyway, defer task

Never block on missing tools — graceful degradation always.

</fallback>

<research>

Trigger research when:
- Tool taking 3x+ longer than expected for task size
- User explicitly asks for better approach
- Task seems like it should have specialized tool
- Current tool missing critical feature
- New tool category needed (not in selection table)

Research workflow:
1. Search for `{TASK} CLI tool 2025` or `{TASK} CLI tool 2024`
2. Check GitHub trending in relevant category
3. Evaluate candidates:
   - Speed: benchmarks vs existing tools
   - Ergonomics: default behavior, output format
   - Maintenance: last commit, issue response time
   - Install: complexity, dependencies
   - Compatibility: OS support, integration

Present findings:
- Tool name + one-line description
- Key advantages over current approach
- Installation command
- Usage example for current task
- Trade-offs or caveats

If research yields strong candidate → add to selection table for future reference.

</research>

<workflow>

Standard flow:

1. **Receive task** → categorize task type (find files, search content, process data)
2. **Check detection** → run script if not yet run this session
3. **Select tool** → use selection table + detection results
4. **Execute** → run command with optimal flags
5. **Evaluate** → if slow/frustrating → trigger research

Research flow:

1. **Trigger identified** → surface to user with `△ This seems slow — research alternatives?`
2. **User confirms** → web search for modern tools
3. **Evaluate candidates** → speed, ergonomics, maintenance
4. **Present findings** → tool + advantages + install + example
5. **Update knowledge** → add to selection table if strong fit

</workflow>

<examples>

**Scenario: Search for authentication code**

Task: Find all files containing "authentication"
Detection: rg available
Selection: Use `rg` over `grep`

```bash
rg "authentication" --type ts --type js
```

**Scenario: Find config files**

Task: Find all YAML files in project
Detection: fd available
Selection: Use `fd` over `find`

```bash
fd -e yaml -e yml
```

**Scenario: Process API response**

Task: Extract specific fields from JSON
Detection: jq unavailable
Fallback: Use node/python
Suggestion: `◇ Alternative: jq would simplify this — install with brew install jq`

```bash
node -e "console.log(JSON.parse(require('fs').readFileSync(0, 'utf-8')).field)"
```

</examples>

<rules>

ALWAYS:
- Run detection script before recommending specific tools
- Use selection table to map task to best available tool
- Provide fallback when suggesting tools that might not be installed
- Surface suggestions for significant improvements (2x+ better)
- Trigger research when tool underperforms expectations

NEVER:
- Assume a tool is installed without checking detection results
- Block workflow on missing non-essential tools
- Recommend abandonware or unmaintained tools
- Use legacy tools when modern alternatives are available
- Skip fallback strategy when preferred tool missing

</rules>

<references>

- [tool-catalog.md](references/tool-catalog.md) — comprehensive tool documentation
- [alternatives.md](references/alternatives.md) — how to research new tools
- [detection-script.md](references/detection-script.md) — detection script implementation

</references>