ast-grep

ast-grep Skill

Structural code search using AST patterns. Use this skill when text-based search (grep/ripgrep) is insufficient.

When to Use This Skill

Activate when user asks to:

• Find code patterns with structural constraints ("async functions without try-catch")
• Locate nested or relational code ("await inside loops")
• Search with negation ("functions that don't have X")
• Rewrite code patterns at scale
• Write custom lint rules

Prefer ast-grep over grep when:

• Pattern involves parent-child or sibling relationships
• Need "contains X but not Y" logic
• Text matching would have too many false positives

Workflow

Step 1: Clarify Requirements

Ask user if unclear:

• What code pattern to find?
• Which programming language?
• Simple match or complex structural query?
• Find only, or also rewrite?

Supported languages: JavaScript, TypeScript, TSX, Python, Rust, Go, Java, C, C++, C#, Kotlin, Swift, Ruby, Lua, HTML, CSS, JSON, YAML

Step 2: Choose Approach

Is it a simple, single-node pattern?
├─ YES → Use `ast-grep run --pattern`
│        Example: ast-grep run --pattern 'console.log($ARG)' --lang javascript .
│
└─ NO → Does it need relational logic (inside/has/precedes/follows)?
        ├─ YES → Create YAML rule with `ast-grep scan --inline-rules`
        │        Consult: references/relational-rules.md
        │
        └─ NO → Does it need composite logic (all/any/not)?
                ├─ YES → Create YAML rule
                │        Consult: references/composite-rules.md
                │
                └─ NO → Use pattern with constraints
                        Consult: references/yaml-config.md

Step 3: Build the Pattern

For simple patterns:

ast-grep run --pattern 'PATTERN' --lang LANGUAGE /path

Meta-variable syntax (consult references/metavariables.md for details):

• $VAR — matches single node
• $$$VAR — matches zero or more nodes
• $_ — matches but doesn't capture

For complex rules, build YAML: