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>

Run detection script before selecting tools:

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.

Map task to best available tool:

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

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.

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.

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

Scenario: Search for authentication code

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

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

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

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

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

• •tool-catalog.md — comprehensive tool documentation
• •alternatives.md — how to research new tools
• •detection-script.md — detection script implementation