# Structural Search

> Structural Search Skill (Hybrid Edition)

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

---

# Structural Search Skill (Hybrid Edition)

Optimized codebase navigation using both text-based (ripgrep) and syntax-aware (ast-grep) engines. This skill implements the "MassGen" progressive refinement protocol to maximize accuracy and minimize token consumption.

## Engines
1. **Text Engine (grep_search)**: Best for strings, comments, and literal identifiers.
2. **Structural Engine (ast-grep)**: Best for finding function definitions, class hierarchies, and complex patterns (e.g., "find all React components with more than 3 props").

## The Hybrid Protocol (Progressive Refinement)
1. **Count First**: Always run a count check if the codebase is large.
2. **Structural Pattern**: Use `$X` as wildcards in `ast-grep` to find logic, not just text.
3. **Scope Limiting**: Force `--type` or `--lang` to avoid scanning unrelated binaries.
4. **Token Guard**: If results > 50, show only the file paths first.

## Usage Examples
- "Find all python functions that return a dictionary: `sg -p 'def $NAME($$$) -> dict: $$$' -l py`"
- "Search for hardcoded API keys in strings: `grep_search pattern='API_KEY='`"
- "Locate all classes extending BaseService: `sg -p 'class $CLASS extends BaseService { $$$ }' -l ts`"

---
*Hybrid Logic: Ripgrep Speed + AST-Grep Intelligence.*