Skills for effective use of developer tooling

version
0.3.1
GitHub stars
13

Install

/plugin install tooling@llm-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pbdeuchler/llm-plugins.

Contents

Discovered from source

Skills 3

Using ast-grep for Structural Code Search

Overview

ast-grep (sg) matches code by AST structure, not text. Use it instead of grep/ripgrep when you need to match code patterns regardless of whitespace, variable names, or formatting. Patterns must be valid, parsable code in the target language.

When to Use

Prefer ast-grep over grep when:

  • Finding function calls with specific argument shapes
  • Matching patterns where variable names differ but structure is the same
  • Rewriting code patterns across a codebase (migrations, deprecations)
  • Finding anti-patterns that regex can't express (e.g. "await inside a loop")

Use grep instead when:

  • Searching for string literals, comments, or non-code text
  • Simple keyword search (import names, error messages)
  • ast-grep is not installed

CLI Quick Reference

# Search for a pattern
sg run -p 'console.log($$$ARGS)' -l javascript src/

# Search and replace (interactive)
sg run -p '$A && $A()' -r '$A?.()' -l typescript --interactive src/

# Apply all replacements without prompting
sg run -p 'var $X = $Y' -r 'const $X = $Y' -l javascript -U src/

# JSON output for programmatic use
sg run -p '$FUNC($$$)' -l python --json src/

# Read from stdin
echo 'let x = 1' | sg run -p 'let $X = $Y' -l javascript --stdin

Metavariable Syntax

SyntaxMatchesExample
$NAMEExactly one AST nodeconsole.log($MSG) matches console.log("hi") but not console.log("hi", 2)
$$$NAMEZero or more nodesconsole.log($$$ARGS) matches any number of arguments
$_NAMEOne node, non-capturing$_OBJ.$METHOD() matches without binding $_OBJ

Reuse enforces equality: $A == $A matches x == x but not x == y.

Language-Specific Patterns

Always pass -l <language>. The language determines how patterns are parsed.

JavaScript/TypeScript:

# Find React hooks
sg run -p 'use$HOOK($$$)' -l typescript src/

# Optional chaining candidates
sg run -p '$A && $A.$B' -r '$A?.$B' -l typescript src/

# Async/await patterns
sg run -p 'await $PROMISE' -l javascript src/

Python:

# Find print statements
sg run -p 'print($$$)' -l python src/

# Dictionary access patterns
sg run -p '$DICT[$KEY]' -l python src/

# With statement patterns
sg run -p 'with open($$$ARGS) as $F: $$$BODY' -l python src/

Go:

# Error handling
sg run -p 'if $ERR != nil { return $$$VALS }' -l go ./

# Function calls
sg run -p '$PKG.$FUNC($$$)' -l go ./

Rust:

# Unwrap calls (potential panics)
sg run -p '$EXPR.unwrap()' -l rust src/

# Match expressions
sg run -p 'match $VAL { $$$ARMS }' -l rust src/

Pattern Pitfalls

MistakeWhy It FailsFix
Using regex in -pPatterns must be valid codeWrite the code structure you want to find
$VAR + NameParsed as $VARN + ameUse constraints or transform in YAML rules
Single quotes in C/Rust patterns'x' is a char literal, not a stringUse "x" for strings
Forgetting -l flagast-grep cannot infer language from patternsAlways specify language explicitly
$A($B, $C) for variadic callsOnly matches exactly 2 argsUse $A($$$ARGS) for any arity

YAML Rules for Complex Matching

When CLI patterns aren't expressive enough, use YAML rules:

id: no-unwrap-in-production
language: rust
rule:
  pattern: $EXPR.unwrap()
  not:
    inside:
      kind: function_item
      has:
        field: name
        regex: '^test_'
message: "Use expect() or proper error handling instead of unwrap()"
severity: warning

Key rule combinators:

  • all: All sub-rules must match (AND)
  • any: Any sub-rule can match (OR)
  • not: Sub-rule must NOT match
  • inside: Target is inside another node
  • has: Target contains a descendant
  • follows/precedes: Sibling ordering

Run rules: sg scan --rule path/to/rule.yml src/

Red Flags

  • Using grep with complex regex when ast-grep would match the structure directly
  • Forgetting $$$ and missing variadic matches
  • Writing patterns that aren't valid code in the target language
  • Not specifying -l and getting parse failures

Using qmd for Knowledge Base Search

Overview

qmd is a local search engine for markdown documents. It combines BM25 keyword search, vector semantic search, and LLM-powered hybrid re-ranking. Use it to find relevant context in documentation, notes, and knowledge bases when grep is too literal and you need conceptual matching.

When to Use

Prefer qmd over grep when:

  • Searching documentation or notes for conceptually related content
  • You know what you're looking for but not the exact terms used
  • You need to find relevant context across a large markdown knowledge base
  • Building context for a task from scattered documentation

Use grep instead when:

  • Searching code files (qmd indexes markdown only)
  • Looking for exact string matches or regex patterns
  • The search target is a known identifier, import, or error message

Search Modes

ModeCommandSpeedBest For
Keyword (BM25)qmd searchFastKnown terms, exact phrases
Semantic (vector)qmd vsearchSlowConceptual queries, fuzzy recall
Hybrid (re-ranked)qmd querySlowestHighest quality, broad exploration

Default to qmd search unless keyword results are insufficient. Escalate to vsearch or query only when needed.

CLI Quick Reference

# Keyword search (fast, use first)
qmd search "authentication flow"

# Semantic search (finds conceptually related content)
qmd vsearch "how users log in"

# Hybrid with LLM re-ranking (most thorough)
qmd query "best practices for session management"

# Restrict to a collection
qmd search "rate limiting" -c api-docs

# More results
qmd search "error handling" -n 20

# Full document content in results
qmd search "deployment" --full

# With line numbers
qmd search "config" --full --line-numbers

# JSON output for structured processing
qmd search "auth" --json --full

# Retrieve a specific document
qmd get "docs/auth.md" --full

# Retrieve from a specific line
qmd get "docs/auth.md:45" -l 100

# Batch retrieve by glob
qmd multi-get "docs/**/*.md" --json

Collection Management

# Add a collection
qmd collection add ~/projects/docs --name project-docs --mask "**/*.md"

# List collections
qmd collection list

# Remove a collection
qmd collection remove old-notes

# Rebuild keyword index
qmd update

# Generate/update vector embeddings (required for vsearch/query)
qmd embed

# Check index health
qmd status

Output Formats

FlagFormatUse Case
(default)Human-readableInteractive use
--jsonJSONProgrammatic processing
--filesCSV: docid,score,filepath,contextFile-oriented workflows
--xmlXMLStructured integration
--mdMarkdownDocumentation pipelines

Filtering and Scoring

# Minimum relevance threshold
qmd search "deployment" --min-score 0.5

# All results above threshold
qmd search "config" --all --min-score 0.3

# Skip large files
qmd search "setup" --max-bytes 50000

Practical Patterns

Gather context before starting a task:

# Find all relevant docs for a feature area
qmd search "authentication" -c project-docs -n 10 --files
# Then retrieve the most relevant ones
qmd get "docs/auth-design.md" --full --line-numbers

Escalation pattern when keywords miss:

# 1. Try keyword first (fast)
qmd search "retry logic"
# 2. If too few results, try semantic
qmd vsearch "how failures are retried"
# 3. If still unclear, use hybrid
qmd query "error recovery and retry mechanisms"

Bulk context loading:

qmd multi-get "design-docs/*.md" --json

Common Mistakes

MistakeFix
Using qmd query for every searchStart with qmd search, escalate only if needed
Forgetting to run qmd embedRequired once before vsearch/query work
Searching code files with qmdqmd indexes markdown only; use grep or ast-grep for code
Not specifying -c with many collectionsRestrict to relevant collection for better signal
Ignoring --min-score with --allUnfiltered results include low-relevance noise

Red Flags

  • Running qmd query repeatedly in a loop (expensive; cache or batch instead)
  • Using qmd when a simple grep for a known string would suffice
  • Forgetting qmd update after documents change
  • Not running qmd embed after adding new collections

Use uv and uvx Instead of Python Directly

Overview

uv is a fast, reproducible Python package and project manager. When uv is on PATH, prefer it over direct python, pip, pipx, and venv calls. It resolves and caches dependencies deterministically, manages the interpreter, and makes ad-hoc tool runs reproducible without polluting the global environment.

Check availability with command -v uv. If uv is not installed, fall back to python/pip as usual - this guidance applies only when uv is present.

Command Mappings

Instead ofUse
python script.pyuv run script.py
python -m moduleuv run python -m module
python -c '...'uv run python -c '...'
python (REPL)uv run python
pip install Xuv pip install X (ad hoc) or uv add X (project dep)
python -m pip install Xuv pip install X
python -m venv .venvuv venv .venv
pipx run Xuvx X
pipx install Xuv tool install X
pip-compile / freezeuv lock / uv pip compile

Why uv run / uvx

  • uv run ensures the project's locked dependencies are present and uses the pinned interpreter before executing - no manual activate step, no stale venv.
  • uvx TOOL runs a CLI tool in an ephemeral, cached environment. Reach for it for one-off tools (uvx ruff check, uvx black ., uvx httpie) instead of globally installing them.
  • For project work, prefer uv add (records the dep in pyproject.toml and the lockfile) over uv pip install (which mutates the environment without recording intent).

Exceptions

  • python --version / python -V capability probes are fine as-is.
  • If the repo standardizes on Poetry, Conda, or plain pip and uv is absent, follow the repo. Do not introduce uv where the project does not use it.
  • An already-activated, project-sanctioned virtualenv is acceptable; do not fight an established workflow.

Quick Reference

uv run app.py                 # run a script with project deps
uv run pytest                 # run an installed dev tool
uvx ruff check .              # run a tool without installing it
uv add httpx                  # add a dependency to the project
uv pip install requests       # ad-hoc install into the active env
uv venv .venv                 # create a virtualenv
uv sync                       # install exactly what the lockfile pins

Hooks 1

Sponsors

Details

Marketplace
pbdeuchler/llm-plugins
Source
plugins/tooling
Author
PBD
Category
Community

More from pbdeuchler/llm-plugins

All 7