# Which Tool

> This skill should be used when choosing CLI tools, a tool seems slow, or when best tool, which tool, or tool alternatives are mentioned.

- Skill: `outfitter-dev/which-tool-2` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add outfitter-dev/which-tool-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/which-tool-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/outfitter-dev/which-tool-2

---


# 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>