Agent skill

cli-ninja

Master CLI navigation and code exploration using modern command-line tools. Use this skill when navigating repositories, searching for files/text/code patterns, or working with structured data (JSON/YAML/XML). Provides guidance on fd (file finding), rg (text search), ast-grep (code structure), fzf (interactive selection), jq (JSON), and yq (YAML/XML).

View SKILL.md on GitHub Repository

Stars 2

Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/pythoninthegrasses/cli-ninja/tree/main/cli-ninja

SKILL.md

CLI Ninja

Overview

This skill provides guidance for efficient repository navigation and code exploration using modern CLI tools. Each tool serves a specific purpose: fd for finding files, rg for searching text, ast-grep for understanding code structure, fzf for interactive selection, jq for JSON manipulation, and yq for YAML/XML processing.

Tool Selection Decision Tree

When navigating or exploring a repository, choose the appropriate tool based on the task:

What are you looking for?

├─ FILES by name/path/extension?
│  └─ Use: fd
│     └─ Need to select from results? → Pipe to fzf
│
├─ TEXT/STRINGS in file contents?
│  └─ Use: rg (ripgrep)
│     └─ Need to select from results? → Pipe to fzf
│
├─ CODE STRUCTURE (functions, classes, imports)?
│  └─ Use: ast-grep
│     └─ Need to select from results? → Pipe to fzf
│     └─ Need to refactor/replace? → Use ast-grep --rewrite
│
├─ Working with JSON data?
│  └─ Use: jq
│
└─ Working with YAML or XML data?
   └─ Use: yq

Quick Reference Guide

fd - Find Files

Basic patterns:

bash

# Find by name
fd 'pattern'

# Find by extension
fd -e py          # All Python files
fd -e 'test.py$'  # Files ending in test.py

# Find in specific directory
fd 'pattern' src/

# Case-insensitive
fd -i readme

# Hidden files
fd -H '.env'

# Exclude patterns
fd -e py -E '*test*'

Common workflows:

bash

# Find and edit a config file interactively
fd config | fzf | xargs $EDITOR

# Find all Python files modified in last 7 days
fd -e py -td --changed-within 7d

# Find files by size
fd -e db --size +100m

See references/fd-patterns.md for comprehensive patterns and flags.

rg - Search Text/Strings

Basic patterns:

bash

# Basic search
rg 'search_term'

# Case-insensitive
rg -i 'search_term'

# Whole word only
rg -w 'word'

# With context lines
rg -C 3 'pattern'        # 3 lines before/after
rg -B 2 -A 5 'pattern'   # 2 before, 5 after

# Specific file types
rg -t py 'import'        # Python files
rg -t rust 'fn main'     # Rust files

Advanced usage:

bash

# Search with line numbers and file names
rg -n 'pattern'

# Multiline search
rg -U 'pattern.*spanning.*lines'

# Exclude patterns
rg 'TODO' -g '!*test*'

# Search in specific directories
rg 'pattern' src/ core/

# JSON output for scripting
rg --json 'pattern'

Interactive workflows:

bash

# Search and open in editor
rg -l 'TODO' | fzf | xargs $EDITOR

# Search with preview
rg --line-number 'pattern' | fzf --preview 'bat --color=always {1} --highlight-line {2}'

See references/rg-patterns.md for regex tips and advanced patterns.

ast-grep - Find Code Structure

Philosophy: ast-grep searches code by structure, not strings. It understands programming language syntax and semantics.

Basic patterns:

Python:

bash

# Find all function definitions
ast-grep --pattern 'def $FUNC($$$)' -l py

# Find specific function calls
ast-grep --pattern 'player.play($$$)' -l py

# Find class definitions
ast-grep --pattern 'class $CLASS:' -l py

# Find all imports of a module
ast-grep --pattern 'from $MOD import $$$' -l py
ast-grep --pattern 'import $MOD' -l py

# Find type annotations
ast-grep --pattern 'def $FUNC($$$) -> $TYPE:' -l py

JavaScript/TypeScript:

bash

# Find React components
ast-grep --pattern 'function $COMP() { $$$ }' -l tsx

# Find useState hooks
ast-grep --pattern 'const [$STATE, $SETTER] = useState($$$)' -l tsx

# Find async functions
ast-grep --pattern 'async function $FUNC($$$) { $$$ }' -l js

# Find imports
ast-grep --pattern 'import $$ from "$MODULE"' -l ts

Rust:

bash

# Find function definitions
ast-grep --pattern 'fn $FUNC($$$) { $$$ }' -l rs

# Find struct definitions
ast-grep --pattern 'struct $NAME { $$$ }' -l rs

# Find impl blocks
ast-grep --pattern 'impl $TRAIT for $TYPE { $$$ }' -l rs

# Find macro usage
ast-grep --pattern 'println!($$$)' -l rs

Go:

bash

# Find function definitions
ast-grep --pattern 'func $FUNC($$$) $$$ { $$$ }' -l go

# Find struct definitions
ast-grep --pattern 'type $NAME struct { $$$ }' -l go

# Find interface implementations
ast-grep --pattern 'func ($RECV $TYPE) $METHOD($$$) $$$ { $$$ }' -l go

# Find goroutines
ast-grep --pattern 'go $FUNC($$$)' -l go

Zig:

bash

# Find function definitions
ast-grep --pattern 'pub fn $FUNC($$$) $$$ { $$$ }' -l zig

# Find struct definitions
ast-grep --pattern 'const $NAME = struct { $$$ };' -l zig

# Find test functions
ast-grep --pattern 'test "$NAME" { $$$ }' -l zig

# Find error handling
ast-grep --pattern 'try $EXPR' -l zig

Ruby:

bash

# Find method definitions
ast-grep --pattern 'def $METHOD($$$); $$$; end' -l rb

# Find class definitions
ast-grep --pattern 'class $CLASS; $$$; end' -l rb

# Find blocks
ast-grep --pattern '$EXPR do |$PARAM|; $$$; end' -l rb

# Find Rails routes
ast-grep --pattern 'get "$PATH", to: "$HANDLER"' -l rb

Refactoring with ast-grep:

bash

# Rename a function across the codebase
ast-grep --pattern 'old_function($$$)' --rewrite 'new_function($$$)' -l py --interactive

# Update API calls
ast-grep --pattern 'api.v1.$METHOD($$$)' --rewrite 'api.v2.$METHOD($$$)' -l py

# Modernize code patterns
ast-grep --pattern 'var $VAR = $EXPR' --rewrite 'const $VAR = $EXPR' -l js

Interactive workflows:

bash

# Find and select a function to edit
ast-grep --pattern 'def $FUNC($$$)' -l py | fzf | cut -d: -f1 | xargs $EDITOR

# Find all TODOs in code comments (use rg instead)
rg 'TODO|FIXME' | fzf

See references/ast-grep-guide.md for comprehensive patterns across all languages.

fzf - Interactive Selection

Basic usage:

bash

# Pipe any list to fzf for selection
command | fzf

# Multi-select mode
command | fzf -m

# With preview window
command | fzf --preview 'bat {}'

Preview configurations:

bash

# Preview files with syntax highlighting
fd -t f | fzf --preview 'bat --color=always {}'

# Preview with line numbers
rg --line-number 'pattern' | fzf --preview 'bat --color=always {1} --highlight-line {2}'

# Preview JSON files
fd -e json | fzf --preview 'jq . {}'

# Custom preview window size
fzf --preview 'cat {}' --preview-window=right:50%

Keybindings:

bash

# ctrl-t: Paste selected files
# ctrl-r: Paste from history
# alt-c: cd into selected directory

# Custom keybindings
fzf --bind 'ctrl-y:execute-silent(echo {} | pbcopy)'

See references/fzf-workflows.md for advanced interactive workflows.

jq - JSON Processing

Basic queries:

bash

# Pretty print
jq . file.json

# Extract field
jq '.name' file.json

# Array indexing
jq '.[0]' file.json

# Nested access
jq '.user.name' file.json

# Array operations
jq '.[] | .name' file.json

Common transformations:

bash

# Filter arrays
jq '.users[] | select(.active == true)' file.json

# Map over arrays
jq '.users | map(.name)' file.json

# Sorting
jq '.users | sort_by(.age)' file.json

# Group by
jq 'group_by(.category)' file.json

# Count items
jq '.items | length' file.json

# Keys extraction
jq 'keys' file.json

Advanced usage:

bash

# Multiple filters
jq '.users[] | select(.age > 18) | .name' file.json

# Construct new objects
jq '{name: .firstName, email: .emailAddress}' file.json

# Combine multiple files
jq -s '.[0] + .[1]' file1.json file2.json

# Read from stdin
curl -s https://api.example.com/data | jq '.results[]'

See references/jq-cookbook.md for comprehensive transformations.

yq - YAML/XML Processing

YAML queries:

bash

# Pretty print
yq . file.yaml

# Extract field
yq '.name' file.yaml

# Nested access
yq '.services.web.image' docker-compose.yml

# Array operations
yq '.dependencies[]' file.yaml

# Convert to JSON
yq -o json . file.yaml

XML queries:

bash

# Parse XML
yq -p xml . file.xml

# Extract elements
yq -p xml '.root.element' file.xml

# Convert XML to JSON
yq -p xml -o json . file.xml

Common operations:

bash

# Update values
yq '.version = "2.0"' file.yaml

# Merge files
yq '. *= load("other.yaml")' file.yaml

# Filter arrays
yq '.items[] | select(.enabled == true)' file.yaml

See references/yq-examples.md for YAML/XML processing patterns.

Combination Workflows

Real-world tasks often combine multiple tools:

1. Find and Edit Files with Context

bash

# Find Python files containing a function, preview them, then edit
rg -l 'def process_data' -t py | fzf --preview 'rg -C 5 "def process_data" {}' | xargs $EDITOR

2. Code Refactoring Workflow

bash

# Find all usages of a function across the codebase
ast-grep --pattern 'old_function($$$)' -l py | fzf -m

# Then refactor with interactive confirmation
ast-grep --pattern 'old_function($$$)' --rewrite 'new_function($$$)' -l py --interactive

3. Interactive Configuration Explorer

bash

# Find config files and explore their structure
fd -e json -e yaml | fzf --preview 'bat --color=always {} --style=numbers'

# Or with jq/yq preview
fd -e json | fzf --preview 'jq . {}'
fd -e yaml | fzf --preview 'yq . {}'

4. Find Related Code

bash

# Find a class definition, then find all its usages
CLASS=$(ast-grep --pattern 'class $NAME:' -l py | fzf | cut -d: -f2)
rg -w "$CLASS" --type py

5. Dependency Analysis

bash

# Find all imports of a module
ast-grep --pattern 'from mymodule import $$$' -l py -t python

# Combine with text search for dynamic imports
rg 'importlib.*mymodule' -t py

6. Multi-File Search and Replace

bash

# Find files with pattern, select multiple, and apply changes
rg -l 'TODO.*urgent' | fzf -m | xargs sed -i '' 's/TODO.*urgent/DONE/g'

7. Code Structure Analysis

bash

# Find all functions in a module, count them
ast-grep --pattern 'def $FUNC($$$)' -l py src/module.py | wc -l

# Find function complexity (functions with many parameters)
ast-grep --pattern 'def $FUNC($A, $B, $C, $D, $E, $$$)' -l py

See scripts/combo-search.sh and scripts/interactive-code-finder.sh for reusable combination workflows.

Best Practices

Performance Tips

Use the right tool for the job:
- File names → fd
- Text content → rg
- Code structure → ast-grep

Narrow your search scope:

bash

# Good: Search specific directory
rg 'pattern' src/

# Better: Search specific file types
rg 'pattern' -t py src/

Use .gitignore respect:
- Both fd and rg respect .gitignore by default
- Use -u or --no-ignore to override when needed

Pattern Matching Tips

ast-grep patterns:
- Use $VAR for single identifiers
- Use $$$ for arbitrary code sequences
- Use $$ for statement lists
ripgrep regex:
- Use -F for literal strings (faster)
- Use -w for whole words
- Use \b for word boundaries
fzf fuzzy matching:
- Space for AND search: foo bar matches files with both
- | for OR search: foo|bar
- ^ for prefix match, $ for suffix match

Debugging Searches

bash

# See what rg is searching
rg --debug 'pattern' 2>&1 | head -20

# Dry-run ast-grep refactoring
ast-grep --pattern 'old' --rewrite 'new' --interactive

# Test jq queries incrementally
echo '{"name":"test"}' | jq .
echo '{"name":"test"}' | jq '.name'

Resources

This skill includes bundled resources to support CLI navigation:

scripts/

Example scripts demonstrating tool combinations:

combo-search.sh - Common combination workflows
interactive-code-finder.sh - Interactive ast-grep + fzf workflow

references/

Comprehensive guides for each tool:

fd-patterns.md - File finding patterns and flags
rg-patterns.md - Text search patterns and regex tips
ast-grep-guide.md - Code structure patterns for Python, Zig, Go, Ruby, JS/TS, Rust
fzf-workflows.md - Interactive selection and preview configurations
jq-cookbook.md - JSON transformations and filters
yq-examples.md - YAML/XML processing examples

Maintainer

pythoninthegrasses Core maintainer

Source details

Full Name: pythoninthegrasses/cli-ninja
Branch: main
Path in repo: cli-ninja
Topics: claude-code claude

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298

Explore

davila7/claude-code-templates

openrlhf-training

High-performance RLHF framework with Ray+vLLM acceleration. Use for PPO, GRPO, RLOO, DPO training of large models (7B-70B+). Built on Ray, vLLM, ZeRO-3. 2× faster than DeepSpeedChat with distributed architecture and GPU resource sharing.

23,776 2,298

Explore

davila7/claude-code-templates

gguf-quantization

GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements.

23,776 2,298

Explore

davila7/claude-code-templates

Claude Code Guide

Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent.

23,776 2,298

Explore

davila7/claude-code-templates

qdrant-vector-search

High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.

23,776 2,298

Explore

davila7/claude-code-templates

behavioral-modes

AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.

23,776 2,298

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

CLI Ninja

Overview

Tool Selection Decision Tree

Quick Reference Guide

fd - Find Files

rg - Search Text/Strings

ast-grep - Find Code Structure

fzf - Interactive Selection

jq - JSON Processing

yq - YAML/XML Processing

Combination Workflows

1. Find and Edit Files with Context

2. Code Refactoring Workflow

3. Interactive Configuration Explorer

4. Find Related Code

5. Dependency Analysis

6. Multi-File Search and Replace

7. Code Structure Analysis

Best Practices

Performance Tips

Pattern Matching Tips

Debugging Searches

Resources

scripts/

references/

Recommended Agent Skills

verl-rl-training

openrlhf-training

gguf-quantization

Claude Code Guide

qdrant-vector-search

behavioral-modes