playbooks

home / skills / 0xdarkmatter / claude-mods / tool-discovery

tool-discovery skill

/skills/tool-discovery

This skill helps you quickly identify the optimal combination of agents and skills for any task, saving time and improving results.

npx playbooks add skill 0xdarkmatter/claude-mods --skill tool-discovery

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

Files (6)
SKILL.md
2.7 KB
---
name: tool-discovery
description: "Recommend the right agents and skills for any task. Covers both heavyweight agents (Task tool) and lightweight skills (Skill tool). Triggers on: which agent, which skill, what tool should I use, help me choose, recommend agent, find the right tool."
allowed-tools: "Read Glob"
depends-on: []
related-skills: [claude-code-templates, claude-code-debug]
---

# Tool Discovery

Recommend the right agents and skills for any task.

## Decision Flowchart

```
Is this a reference/lookup task?
├── YES → Use a SKILL (lightweight, auto-injects)
└── NO → Does it require reasoning/decisions?
         ├── YES → Use an AGENT (heavyweight, spawns subagent)
         └── MAYBE → Check catalogs below
```

**Rule:** Skills = patterns/reference. Agents = decisions/expertise.

## Quick Skill Reference

| Skill | Triggers |
|-------|----------|
| **file-search** | fd, rg, fzf, find files |
| **find-replace** | sd, batch replace |
| **code-stats** | tokei, difft, line counts |
| **data-processing** | jq, yq, json, yaml |
| **structural-search** | ast-grep, sg, ast pattern |
| **git-workflow** | lazygit, gh, delta, rebase |
| **python-env** | uv, venv, pyproject |
| **rest-patterns** | http methods, status codes |
| **sql-patterns** | cte, window functions |
| **sqlite-ops** | sqlite, aiosqlite |
| **tailwind-patterns** | tailwind, tw classes |
| **mcp-patterns** | mcp server, protocol |

## Quick Agent Reference

| Agent | Triggers |
|-------|----------|
| **python-expert** | Python, async, pytest |
| **typescript-expert** | TypeScript, types, generics |
| **react-expert** | React, hooks, state |
| **postgres-expert** | PostgreSQL, query optimization |
| **cloudflare-expert** | Workers, KV, D1, R2 |
| **Explore** | "where is", "find" |
| **Plan** | design, architect |

## How to Launch

**Skills:**
```
Skill tool → skill: "file-search"
```

**Agents:**
```
Task tool → subagent_type: "python-expert"
         → prompt: "Your task"
```

## Match by Task Type

| Task | Skill First | Agent If Needed |
|------|-------------|-----------------|
| "How to write a CTE?" | sql-patterns | sql-expert |
| "Optimize this query" | — | postgres-expert |
| "Find files named X" | file-search | Explore |
| "Set up Python project" | python-env | python-expert |
| "What HTTP status for X?" | rest-patterns | — |

## Tips

- **Skills are cheaper** - Use for lookups, patterns
- **Agents are powerful** - Use for decisions, optimization
- **Don't over-recommend** - Max 2-3 tools per task

## Additional Resources

For complete catalogs, load:
- `./references/agents-catalog.md` - All agents with capabilities
- `./references/skills-catalog.md` - All skills with details

Overview

This skill recommends the right agents and skills for any task, distinguishing lightweight reference patterns from heavyweight decision-making agents. It maps common task triggers to the appropriate tool and limits recommendations to 2–3 options. The goal is faster, cost-effective tool selection so you run the smallest, most capable tool for the job.

How this skill works

It inspects the user request for intent and trigger keywords (lookup, replace, search, optimize, design, etc.). If the task is a reference or pattern lookup it recommends a Skill; if it requires reasoning, orchestration, or optimization it recommends an Agent. It also provides launch snippets showing how to start a Skill or spawn a subagent.

When to use it

  • You need a quick lookup, pattern, or transformation (use a Skill).
  • You need design, optimization, or layered decision-making (use an Agent).
  • You’re unsure which tool fits—ask for a recommendation with the task description.
  • You want to limit cost and complexity—prefer Skills for simple lookups.
  • You must spawn language-guided workflows or run tests—prefer Agents.

Best practices

  • Prefer Skills for deterministic lookups and pattern matching to save cost.
  • Limit recommendations to 2–3 tools to avoid analysis paralysis.
  • Match triggers to quick skill/agent tables (file-search, sql-patterns, python-expert).
  • Use Agents when the task requires multi-step reasoning, code changes, or performance tuning.
  • Provide a concise task prompt when spawning a subagent (one-line objective + constraints).

Example use cases

  • Find all files named X in a repo → recommend file-search skill or Explore agent if broad discovery is needed.
  • Perform a batch find-and-replace across a codebase → recommend find-replace skill.
  • Optimize a slow SQL query → recommend postgres-expert agent, not a skill.
  • Set up a new Python project environment → recommend python-env skill first, escalate to python-expert for custom architecture.
  • Decide which HTTP status code to return → recommend rest-patterns skill for guidelines.

FAQ

How do I know when to escalate a Skill to an Agent?

Escalate when the task needs judgment, multi-step planning, or code changes that require testing and verification; use Skills for single-step lookups or pattern matching.

Can you recommend more than one tool?

Yes, but keep it to 2–3 complementary options: one primary recommendation and up to two alternatives.