code-structural-search
Use ast-grep for AST-based code pattern matching.
How do I install this agent skill?
npx skills add https://github.com/oimiragieo/agent-studio --skill code-structural-searchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive library of patterns and instructions for using ast-grep, a tool for structural code search and analysis. It is designed to assist with refactoring, code quality checks, and security auditing.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 1 issue
- Runlayerpass
4/12 files flagged
What does this agent skill do?
Code Structural Search
Use ast-grep for AST-based code pattern matching.
When to Use
- Find code by structure, not keywords
- "Find all functions with 3 arguments"
- "Find all classes that extend X"
- "Find all database queries"
- "Find all error handling patterns"
- Precise code refactoring (change exact patterns)
Interface
Skill({ skill: 'code-structural-search', args: 'pattern-here --lang ts' });
Language Support
ast-grep supports 20+ languages via tree-sitter:
| Language | Flag | File Extensions |
|---|---|---|
| JavaScript | --lang js | .js, .jsx |
| TypeScript | --lang ts | .ts, .tsx |
| Python | --lang py | .py, .pyi |
| Go | --lang go | .go |
| Rust | --lang rs | .rs |
| Java | --lang java | .java |
| C | --lang c | .c, .h |
| C++ | --lang cpp | .cpp, .cc, .hpp, .hh |
| C# | --lang cs | .cs |
| Kotlin | --lang kt | .kt, .kts |
| Swift | --lang swift | .swift |
| PHP | --lang php | .php |
| Ruby | --lang rb | .rb |
| Lua | --lang lua | .lua |
| Elixir | --lang ex | .ex, .exs |
| HTML | --lang html | .html, .htm |
| CSS | --lang css | .css |
| JSON | --lang json | .json |
| Bash | --lang bash | .sh, .bash |
| Thrift | --lang thrift | .thrift |
Pattern Examples
JavaScript/TypeScript
Find all functions:
function $NAME($ARGS) { $$ }
Find functions with exactly 2 arguments:
function $NAME($A, $B) { $$ }
Find async functions:
async function $NAME($ARGS) { $$ }
Find class methods:
class $NAME {
$METHOD($ARGS) { $$ }
}
Find arrow functions:
const $NAME = ($ARGS) => { $$ }
Find console.log statements:
console.log($$$)
Find try-catch blocks:
try { $$ } catch ($ERR) { $$ }
Python
Find all functions:
def $NAME($ARGS): $$$
Find class definitions:
class $NAME: $$$
Find async functions:
async def $NAME($ARGS): $$$
Find imports:
import $MODULE
Find from imports:
from $MODULE import $$$
Go
Find all functions:
func $NAME($ARGS) $RETURN { $$ }
Find struct definitions:
type $NAME struct { $$$ }
Find interface definitions:
type $NAME interface { $$$ }
Rust
Find all functions:
fn $NAME($ARGS) -> $RETURN { $$ }
Find impl blocks:
impl $NAME { $$$ }
Find pub functions:
pub fn $NAME($ARGS) -> $RETURN { $$ }
Java
Find all methods:
public $RETURN $NAME($ARGS) { $$ }
Find class definitions:
public class $NAME { $$$ }
Find interface definitions:
public interface $NAME { $$$ }
Pattern Syntax
| Symbol | Meaning | Example |
|---|---|---|
$NAME | Single node/identifier | function $NAME() {} |
$$$ | Zero or more statements/nodes | class $NAME { $$$ } |
$$ | Zero or more statements (block) | if ($COND) { $$ } |
$_ | Anonymous wildcard (discard) | console.log($_) |
Performance
- Speed: <50ms per search (typical)
- Best combined with semantic search (Phase 1)
- Use ripgrep first for initial file discovery
vs Other Tools
vs Ripgrep (grep):
- Ripgrep: Fast text search, finds keywords
- ast-grep: Structural search, finds exact code patterns
- Use ripgrep first → then ast-grep to refine
vs Semantic Search (Phase 1):
- Semantic: Understands code meaning
- ast-grep: Understands code structure
- Combined: Best results (Phase 2)
Usage Workflow
-
Broad search with ripgrep:
Skill({ skill: 'ripgrep', args: 'authenticate --type ts' }) -
Structural refinement with ast-grep:
Skill({ skill: 'code-structural-search', args: 'function authenticate($$$) { $$ } --lang ts' }) -
Semantic understanding with Phase 1:
Skill({ skill: 'code-semantic-search', args: 'authentication logic' })
Common Use Cases
Security Patterns
Find unvalidated inputs:
router.post($PATH, ($REQ, $RES) => { $$ })
Find SQL queries (potential injection):
db.query(`SELECT * FROM ${$VAR}`)
Find eval usage:
eval($$$)
Code Quality Patterns
Find deeply nested functions:
function $NAME($ARGS) {
if ($COND) {
if ($COND2) {
if ($COND3) { $$ }
}
}
}
Find long parameter lists (>5 params):
function $NAME($A, $B, $C, $D, $E, $F, $$$) { $$ }
Find unused variables:
const $NAME = $VALUE;
Refactoring Patterns
Find old API usage:
oldAPI.deprecatedMethod($$$)
Find callback patterns (convert to async/await):
$FUNC($ARGS, ($ERR, $DATA) => { $$ })
Find React class components (convert to hooks):
class $NAME extends React.Component { $$$ }
Iron Laws
- ALWAYS specify the language with
--langflag — without a language flag, ast-grep applies heuristics that produce false positives; specify--lang ts,--lang py, etc. for accurate AST parsing. - ALWAYS use ripgrep/keyword search first to narrow the target set — structural search over the whole codebase is slow; use ripgrep to find candidate files first, then apply ast-grep for precise matching.
- NEVER use regex for structural code patterns — regex breaks on formatting differences, nested structures, and multi-line code; AST patterns are format-independent and semantically precise.
- ALWAYS test patterns on a known match before running project-wide — patterns with incorrect syntax silently match nothing; verify the pattern finds at least one known example before broad application.
- ALWAYS use
$$$for variable argument lists, not*or.— ast-grep uses metavariable syntax ($NAME,$$$,$$); regex or glob syntax in patterns produces silent failures.
Anti-Patterns
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
No --lang flag | Wrong parser applied; produces false positives and misses | Always specify --lang ts, --lang py, etc. |
| Running project-wide without ripgrep pre-filter | Slow on large codebases; many irrelevant results | Use ripgrep to identify candidate files first |
| Regex for structural matching | Breaks on multi-line, whitespace variations, nesting | Use ast-grep AST patterns ($NAME, $$$, etc.) |
| Untested pattern on full codebase | Incorrect patterns silently return nothing | Test on one known match first |
Using * or . for wildcards | Not valid ast-grep syntax; ignored or errors | Use $NAME for single node, $$$ for sequences |
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
- New pattern →
.claude/context/memory/learnings.md - Issue found →
.claude/context/memory/issues.md - Decision made →
.claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oimiragieo/agent-studio/code-structural-search">View code-structural-search on skillZs</a>