ast-grep · skempken — Claude Code skill: what it does, how to install
The ast-grep skill brings AST-based search, linting, and rewrites to coding agents. Use it for structural refactors, code analysis, and custom rules.
MIT 1 installs ★ 5 updated 2025-10-31
npx skills add skempken/ast-grep-skill --skill ast-grep -a claude-codeWhat ast-grep does
ast-grep works with abstract syntax trees, so it can match code structure instead of raw text. The skill covers pattern syntax, meta-variables, rule configuration, and CLI usage for JavaScript, TypeScript, Python, Rust, Go, Java, and other languages. It is designed for searches, lint checks, and structural rewrites.
Use ast-grep run for direct searches, replacements, stdin input, or JSON results. Project rules run through ast-grep scan, while ast-grep test validates rule tests. The ast-grep new command creates a project, a rule, or a test scaffold.
Rules can combine pattern, kind, regex, relational checks such as inside and has, and composite conditions. Java annotation checks need structural matching with kind and has, and Java rules use language: Java. That distinction matters when a text match would also catch strings or comments.
What it helps with
- search code by AST structure
- rewrite legacy syntax from a pattern
- define a YAML lint rule
- validate rule behavior with tests
- inspect matches as JSON
Example prompts for the agent
- Use
ast-grep runto findconsole.logcalls in JavaScript and return the matches. - Find
var $VAR = $VALand rewrite it aslet $VAR = $VALwithast-grep run; leave the changes unapplied. - Create a
no-consolerule, run it withast-grep scan, and validate it withast-grep test.
How to install ast-grep
1Skills CLI (Vercel)
npx skills add skempken/ast-grep-skill --skill ast-grep -a claude-code2Manually: put the files in place
~/.claude/skills/ast-grep/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ast-grep/
1Skills CLI (Vercel)
npx skills add skempken/ast-grep-skill --skill ast-grep -a codex2Manually: put the files in place
.agents/skills/ast-grep/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add skempken/ast-grep-skill --skill ast-grep -a cursor2Manually: put the files in place
.cursor/skills/ast-grep/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install skempken/ast-grep-skill .claude/skills/ast-grep2Manually: put the files in place
.github/skills/ast-grep/SKILL.md1Skills CLI (Vercel)
npx skills add skempken/ast-grep-skill --skill ast-grep -a gemini-cli2Platform CLI
gemini skills install https://github.com/skempken/ast-grep-skill --path .claude/skills/ast-grepManually: put the files in place
.devin/skills/ast-grep/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add skempken/ast-grep-skill --skill ast-grep -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ast-grep
How do I install ast-grep in Claude Code?
Run npx skills add skempken/ast-grep-skill --skill ast-grep -a claude-code, then check ~/.claude/skills/ast-grep/SKILL.md.
What does ast-grep do?
It searches, lints, and rewrites code through AST patterns. The skill explains meta-variable syntax, YAML rule structure, and the CLI commands used for these workflows.
How does ast-grep handle Java annotations?
Java annotation checks use structural rules with kind: method_declaration, has, and an annotation pattern. Set language: Java in the rule.
Source text
SKILL.md · MIT
---
name: ast-grep
description: Use this skill when working with ast-grep, an AST-based code search, lint, and rewrite tool. Activate when the user asks to search code patterns, refactor code structurally, create linting rules, or perform AST-based code analysis. Helps with pattern syntax, meta-variables, rule configuration, and CLI commands for Java, JavaScript, TypeScript, Python, Rust, Go, and 20+ other languages. Includes Java-specific patterns for annotations, null checks, exception handling, and Stream API usage.
---
# ast-grep Skill
You now have access to ast-grep, a powerful AST-based code search, lint, and rewrite tool. Use this skill when working with code analysis, refactoring, or pattern matching tasks.
## What is ast-grep?
ast-grep is a command-line tool that searches, lints, and rewrites code using Abstract Syntax Trees (ASTs) rather than plain text. Think of it as "a hybrid of grep, eslint, and codemod."
**Key advantages over text-based tools:**
- Structurally aware: matches code patterns, not just text
- Language-aware: understands syntax across 20+ languages
- Precise: avoids false positives from string/comment matches
- Fast: written in Rust with multi-core support
**Supported languages:** C, C++, Rust, Go, Java, Python, C#, JavaScript, TypeScript, HTML, CSS, Kotlin, Swift, JSON, YAML, and more.
## Core Commands
### 1. ast-grep run (Quick searches & rewrites)
```bash
# Basic pattern search (JavaScript)
ast-grep run -p 'console.log($MSG)' -l javascript
# Basic pattern search (Java)
ast-grep run -p 'System.out.println($MSG)' -l java
# Search and rewrite (JavaScript)
ast-grep run -p 'var $VAR = $VAL' -r 'let $VAR = $VAL' -l javascript
# Search and rewrite (Java)
ast-grep run -p 'new Date()' -r 'LocalDate.now()' -l java
# Apply all changes (use after user approval)
ast-grep run -p 'PATTERN' -r 'REWRITE' -U
# Get JSON output for analysis
ast-grep run -p 'PATTERN' --json
# From stdin
echo "var x = 1" | ast-grep run --stdin -l javascript -p 'var $V = $VAL'
```
### 2. ast-grep scan (Rule-based linting)
```bash
# Scan with all rules in project
ast-grep scan
# Use specific rule file
ast-grep scan -r path/to/rule.yml
# Filter rules by regex
ast-grep scan --filter 'no-console'
# Inline rule
ast-grep scan --inline-rules 'id: test
language: JavaScript
rule:
pattern: console.log($A)'
```
### 3. ast-grep test (Validate rules)
```bash
# Run tests for rules
ast-grep test
# Update all snapshots
ast-grep test -U
```
### 4. ast-grep new (Generate templates)
```bash
# Create new project structure
ast-grep new project
# Create new rule
ast-grep new rule my-rule
# Create new test
ast-grep new test my-test
```
## Pattern Syntax
### Meta Variables
Meta variables capture AST nodes and enable flexible pattern matching:
**Format:** `$` + uppercase letters/underscores/digits
- Valid: `$VAR`, `$META_1`, `$_TEMP`, `$A`
- Invalid: `$invalid`, `$camelCase`, `$123`
**Usage:**
```javascript
// JavaScript Pattern: $OBJ.$METHOD($$$ARGS)
// Matches: user.save(data)
// api.call(x, y, z)
// obj.method()
```
```java
// Java Pattern: $OBJ.$METHOD($$$ARGS)
// Matches: user.getName()
// list.add(item)
// stream.collect(Collectors.toList())
```
**Capturing constraints:** Reusing the same variable name ensures matched code is identical:
```javascript
// Pattern: $X == $X
// Matches: a == a ✓
// Doesn't match: a == b ✗
```
**Non-capturing variables:** Prefix with `_` to match without capturing (performance optimization):
```javascript
// Pattern: $_OBJ.method()
// Matches method calls on any object without storing the object
```
### Multi-Node Matching
Use `$$$` to match zero or more AST nodes:
```javascript
// Pattern: function $FUNC($$$PARAMS) { $$$ }
// Matches any function with any number of parameters
```
**Named multi-node:**
```javascript
// Pattern: someFunc($$$ARGS)
// Captures all arguments as $$$ARGS
```
### Pattern Types
**1. Code Patterns** (most common)
```yaml
pattern: console.log($MSG)
```
**2. Kind Patterns** (match node types)
```yaml
kind: function_declaration
```
**3. Regex Patterns**
```yaml
regex: "^test_.*"
```
## Rule Configuration
Rules are written in YAML with three essential fields:
```yaml
id: unique-rule-identifier # Required
language: JavaScript # Required: determines which files to scan
rule: # Required: matching logic
pattern: console.log($A)
```
### Rule Categories
**1. Atomic Rules** - Match single node properties
```yaml
rule:
pattern: Promise.all($PROMISES)
```
**2. Relational Rules** - Match node relationships
```yaml
rule:
pattern: await $EXPR
inside:
kind: function_declaration # Not inside async function
not:
has:
kind: async
```
**3. Composite Rules** - Combine multiple rules
```yaml
rule:
all: # All conditions must match
- pattern: $VAR = $VAL
- not:
inside:
kind: function_declaration
any: # At least one must match
- pattern: var $V
- pattern: let $V
```
### Rule Object Fields
| Field | Category | Purpose |
|-------|----------|---------|
| `pattern` | Atomic | Match code patterns |
| `kind` | Atomic | Match AST node types |
| `regex` | Atomic | Match with regex |
| `inside` | Relational | Node must be inside matched pattern |
| `has` | Relational | Node must contain matched pattern |
| `follows` | Relational | Node must come after pattern |
| `precedes` | Relational | Node must come before pattern |
| `all` | Composite | All sub-rules must match (AND) |
| `any` | Composite | At least one sub-rule must match (OR) |
| `not` | Composite | Pattern must NOT match |
| `matches` | Utility | Reference other rules by ID |
### Advanced Rule Example
```yaml
id: no-await-in-promise-all
language: TypeScript
message: Avoid await inside Promise.all
note: Use Promise.all to parallelize async operations
severity: warning
rule:
pattern: Promise.all($PROMISES)
has:
pattern: await $_
stopBy: end # Stop searching at expression boundaries
fix: |
Remove await from $PROMISES
```
## Java-Specific Patterns
Java has unique syntax features that require special handling in ast-grep. This section covers patterns specifically for Java development.
### Working with Annotations
Annotations are a core Java feature but complicate simple pattern matching. Use structural rules with `kind` and `has`:
```yaml
# Find all methods with @Deprecated annotation
id: find-deprecated-methods
language: Java
rule:
kind: method_declaration
has:
kind: marker_annotation
pattern: "@Deprecated"
```
```yaml
# Find JUnit test methods without assertions
id: test-without-assertions
language: Java
rule:
kind: method_declaration
has:
kind: marker_annotation
pattern: "@Test"
not:
has:
any:
- pattern: assert$$$($$$)
- pattern: assertEquals($$$)
- pattern: assertTrue($$$)
message: Test method lacks assertions
```
### Field Declarations with Modifiers
**Critical Gotcha:** Cannot use meta-variables in modifier positions!
```yaml
# ❌ FAILS - Cannot parse $MOD as valid syntax
pattern: $MOD String $FIELD;
# ✓ CORRECT - Use structural targeting
id: find-string-fields
language: Java
rule:
kind: field_declaration
has:
field: type
regex: ^String$
```
```yaml
# Find fields of specific type regardless of modifiers
id: find-list-fields
language: Java
rule:
kind: field_declaration
has:
pattern: List<$T> $NAME
```
### Exception Handling
```yaml
# Detect empty catch blocks
id: empty-catch-block
language: Java
rule:
kind: catch_clause
has:
pattern: |
catch ($E) {
}
message: Empty catch block - handle or log exception
severity: warning
```
```yaml
# Find try blocks without catch or finally
id: incomplete-try
language: Java
rule:
kind: try_statement
not:
any:
- has:
kind: catch_clause
- has:
kind: finally_clause
message: Try statement must have catch or finally
severity: error
```
### Null Safety Patterns
```yaml
# Find potential NullPointerException risks
id: missing-null-check
language: Java
rule:
pattern: $OBJ.$METHOD($$$)
not:
any:
- inside:
pattern: if ($OBJ != null) { $$$ }
- inside:
pattern: if (Objects.nonNull($OBJ)) { $$$ }
- inside:
pattern: if (Objects.requireNonNull($OBJ)) { $$$ }
message: Potential NullPointerException - add null check
note: Consider using Optional or Objects.requireNonNull()
```
### Optional Anti-patterns
```yaml
# Detect Optional.get() without isPresent() check
id: optional-get-without-check
language: Java
rule:
pattern: $OPT.get()
not:
inside:
any:
- pattern: if ($OPT.isPresent()) { $$$ }
- pattern: $OPT.orElse($$$)
- pattern: $OPT.orElseGet($$$)
- pattern: $OPT.orElseThrow($$$)
message: Optional.get() called without isPresent() check
note: Use orElse(), orElseGet(), or orElseThrow() instead
severity: warning
```
### Stream API Patterns
```yaml
# Detect streams created but not consumed
id: stream-without-terminal
language: Java
rule:
pattern: $LIST.stream().$$$OPS
not:
has:
regex: "\\.(collect|forEach|reduce|count|findFirst|findAny|allMatch|anyMatch|noneMatch|toArray)\\("
message: Stream created but not consumed with terminal operation
```
```yaml
# Warn about sequential operations that could be parallel
id: sequential-stream-on-large-collection
language: Java
rule:
all:
- pattern: $LARGE_LIST.stream().$$$
- has:
regex: "(filter|map|flatMap)"
message: Consider parallelStream() for large collections
note: Profile first to ensure parallel processing benefits outweigh overhead
severity: info
```
### Resource Management
```yaml
# Enforce try-with-resources for AutoCloseable
id: use-try-with-resources
language: Java
rule:
all:
- kind: local_variable_declaration
- has:
regex: "(Stream|Connection|Statement|Reader|Writer|InputStream|OutputStream|Scanner|BufferedReader)"
- not:
inside:
kind: resource_specification
message: Resource should be managed with try-with-resources
note: Ensures resources are closed even if exceptions occur
severity: warning
```
### Security Patterns
```yaml
# Detect potential SQL injection via string concatenation
id: sql-injection-risk
language: Java
rule:
all:
- pattern: $QUERY + $INPUT
- has:
kind: identifier
regex: "(?i)(query|sql|select|insert|update|delete)"
message: Potential SQL injection - use PreparedStatement
note: Never concatenate user input into SQL queries
severity: error
```
```yaml
# Find hardcoded passwords or credentials
id: hardcoded-credentials
language: Java
rule:
kind: variable_declarator
has:
pattern: $VAR = "$VALUE"
has:
kind: identifier
regex: "(?i)(password|passwd|pwd|secret|key|token|credential)"
message: Hardcoded credential detected
note: Use environment variables or secure configuration
severity: error
```
### Generics and Type Matching
```yaml
# Find raw type usage (missing generics)
id: raw-type-usage
language: Java
rule:
pattern: List $VAR = new ArrayList()
message: Use generic types - List<Type> instead of raw List
fix: List<Object> $VAR = new ArrayList<>()
```
### Java AST Node Types Reference
Common node types for structural rules:
**Declarations:**
- `class_declaration` - Class definitions
- `interface_declaration` - Interface definitions
- `enum_declaration` - Enum definitions
- `record_declaration` - Record definitions (Java 14+)
- `method_declaration` - Method definitions
- `field_declaration` - Field/member variable definitions
- `constructor_declaration` - Constructor definitions
- `local_variable_declaration` - Local variable definitions
**Statements:**
- `try_statement` - Try-catch blocks
- `try_with_resources_statement` - Try-with-resources
- `if_statement` - If conditionals
- `for_statement` - For loops
- `enhanced_for_statement` - For-each loops
- `while_statement` - While loops
- `synchronized_statement` - Synchronized blocks
- `switch_expression` - Switch expressions (Java 12+)
- `return_statement` - Return statements
- `throw_statement` - Throw statements
**Expressions:**
- `method_invocation` - Method calls
- `object_creation_expression` - New object instantiation
- `lambda_expression` - Lambda expressions
- `method_reference` - Method references (::)
- `field_access` - Field access (obj.field)
- `array_access` - Array indexing
- `cast_expression` - Type casts
- `instanceof_expression` - instanceof checks
- `ternary_expression` - Ternary operator (? :)
**Annotations:**
- `annotation` - Annotations with values
- `marker_annotation` - Annotations without values (@Override)
**Generics:**
- `type_arguments` - Generic type arguments <T>
- `type_parameters` - Generic type parameters
- `wildcard` - Generic wildcards (? extends, ? super)
### Java-Specific Gotchas
**1. Modifier Patterns Don't Work**
```yaml
# ❌ Fails - ERROR node in AST
pattern: public static $TYPE $METHOD($$$)
# ✓ Use structural approach
rule:
kind: method_declaration
regex: "public.*static"
```
**2. Annotations Break Simple Patterns**
```java
// Pattern: String $FIELD;
// Won't match: @NotNull String field;
// Reason: Annotation changes AST structure
// Solution: Use kind: field_declaration with has constraints
```
**3. Generic Type Complexity**
```yaml
# Simple pattern may fail with complex generics
pattern: Map<String, List<Integer>> $VAR
# More reliable: Use kind + regex on type field
rule:
kind: local_variable_declaration
has:
field: type
regex: "^Map<"
```
**4. Import Handling**
```yaml
# May need to match both forms
any:
- pattern: "@Test" # Import org.junit.Test
- pattern: "@org.junit.Test" # Fully qualified
```
**5. Lambda vs Method Syntax**
```yaml
# Different AST structures
- kind: lambda_expression # () -> expr
- kind: method_reference # Class::method
# Must match separately!
```
## Using ast-grep with Claude Code
**IMPORTANT:** This skill is designed for Claude Code's programmatic usage. Claude cannot use interactive mode.
### Recommended Workflow
When using ast-grep through Claude Code, follow this pattern:
**1. Search and Analyze**
```bash
# Use --json to get structured output for analysis
ast-grep run -p 'console.log($A)' -l javascript --json
```
**2. Present Findings to User**
Claude should review the JSON output and present findings to the user with:
- What was found
- Locations (file paths and line numbers)
- Proposed changes (if applicable)
**3. Apply Changes (Only After User Approval)**
```bash
# Use -U to apply all changes automatically
ast-grep run -p 'console.log($A)' -r 'logger.info($A)' -l javascript -U
```
**DO NOT use `--interactive` flag** - it requires human input and will fail in Claude Code.
### Example Claude Code Workflow
```bash
# Step 1: Find all matches
ast-grep run -p 'var $VAR = $VAL' -l javascript --json
# Claude analyzes JSON, shows user: "Found 15 var declarations in 8 files"
# User says: "Please update them to let"
# Step 2: Apply changes with user approval
ast-grep run -p 'var $VAR = $VAL' -r 'let $VAR = $VAL' -l javascript -U
```
## Best Practices
### 1. Always Use --json for Analysis
```bash
# Get structured output for Claude to parse
ast-grep run -p 'console.log($A)' -l javascript --json
ast-grep scan --json
```
### 2. Use the Right Tool for the Job
- **Quick one-off searches:** `ast-grep run` with `--json`
- **Recurring checks:** `ast-grep scan` with rules
- **Code refactoring:** `ast-grep run` with `--rewrite` and `-U` (after user approval)
- **CI/CD integration:** `ast-grep scan` with JSON output
### 3. Leverage Relational Rules
Instead of complex regex, use AST relationships:
```yaml
# Find console.log NOT inside try-catch
rule:
pattern: console.log($A)
not:
inside:
pattern: try { $$$ } catch ($E) { $$$ }
```
### 4. Test Rules Before Deploying
Always create tests for your rules:
```yaml
# In rule-test.yml
id: no-console-log
testCases:
- id: should-match
match: console.log("test")
- id: should-not-match
match: logger.info("test")
```
Run: `ast-grep test`
### 5. Understand Language-Specific Patterns
Patterns must be valid code in the target language:
```yaml
# JavaScript: snake_case and camelCase are different
pattern: my_function() # Won't match myFunction()
# Python: indentation matters for blocks
pattern: |
if $COND:
$BODY
```
## Common Pitfalls & Solutions
### Pitfall 1: Invalid Meta Variable Names
```bash
# ❌ Wrong: lowercase letters
pattern: $myVar = $value
# ✓ Correct: uppercase only
pattern: $MY_VAR = $VALUE
```
### Pitfall 2: Language Mismatch
```bash
# ❌ Wrong: using Python syntax for JavaScript
ast-grep run -p 'print($A)' -l javascript
# ✓ Correct: use console.log for JavaScript
ast-grep run -p 'console.log($A)' -l javascript
```
### Pitfall 3: Forgetting --lang with stdin
```bash
# ❌ Wrong: ast-grep can't infer language
echo "code" | ast-grep run -p 'pattern'
# ✓ Correct: specify language
echo "code" | ast-grep run -p 'pattern' --stdin -l python
```
### Pitfall 4: Overly Broad Patterns
```yaml
# ❌ Too broad: matches everything
pattern: $A
# ✓ Specific: matches the structure you want
pattern: if ($COND) { $BODY }
```
### Pitfall 5: Not Using stopBy in Relational Rules
```yaml
# Without stopBy, search is unlimited (slow & imprecise)
rule:
pattern: Promise.all($A)
has:
pattern: await $_
stopBy: end # Stop at expression boundaries for performance
```
## Useful Flags
| Flag | Purpose | Example | Claude Code Usage |
|------|---------|---------|-------------------|
| `-p, --pattern` | Search pattern | `-p 'console.log($A)'` | ✓ Use |
| `-r, --rewrite` | Replacement code | `-r 'logger.info($A)'` | ✓ Use |
| `-l, --lang` | Specify language | `-l javascript` | ✓ Use |
| `--json` | Machine-readable output | `--json` | ✓ **Always use** for analysis |
| `-U, --update-all` | Apply all changes | `-U` | ✓ Use after user approval |
| `--stdin` | Read from stdin | `--stdin` | ✓ Use when needed |
| `--debug-query` | Debug pattern matching | `--debug-query` | ✓ Use for troubleshooting |
| `-j, --threads` | Control parallelization | `-j 4` | ✓ Use |
| `-i, --interactive` | Manual review of each change | `--interactive` | ✗ **DO NOT USE** - requires human input |
## Integration Examples
### With jq (JSON processing)
```bash
ast-grep scan --json | jq '.[] | select(.severity == "error")'
```
### With git (changed files only)
```bash
git diff --name-only | xargs ast-grep run -p 'pattern'
```
### CI/CD Integration
```bash
# Exit with error if issues found
ast-grep scan --json > results.json
if [ $(jq length results.json) -gt 0 ]; then
exit 1
fi
```
## When to Use ast-grep
**✓ Use ast-grep for:**
- Code refactoring across multiple files
- Finding complex code patterns (nested structures, specific contexts)
- Enforcing code standards (custom linting rules)
- Language-aware code search
- Safe automated code transformations
**✗ Don't use ast-grep for:**
- Simple string searches (use grep/ripgrep)
- Comment/documentation searches
- Binary file searches
- When exact character positions matter more than syntax
## Quick Reference
```bash
# Search for a pattern
ast-grep run -p 'PATTERN' -l LANG [FILES]
# Search and replace
ast-grep run -p 'PATTERN' -r 'REPLACEMENT' -l LANG
# Scan with rules
ast-grep scan [--rule RULE_FILE]
# Test rules
ast-grep test
# Generate completions
ast-grep completions bash > ~/.bash_completion.d/ast-grep
```
## Additional Resources
- Online Playground: https://ast-grep.github.io/playground.html
- Documentation: https://ast-grep.github.io/
- Pattern Catalog: Explore pre-built patterns for common tasks
- Language Reference: Check language-specific node types and syntax
## Workflow for Complex Refactoring (Claude Code)
1. **Explore:** Use `ast-grep run -p 'pattern' --json` to find all matches
2. **Analyze:** Parse JSON output and present findings to user
3. **Test:** Create a rule with tests: `ast-grep new rule my-rule`
4. **Apply:** After user approval, use `-U` to apply all changes
5. **Validate:** Run tests and build to ensure correctness
Remember: ast-grep operates on AST structure, not text. Always think in terms of code syntax, not string patterns.
© skempken · MIT · skempken/ast-grep-skill
Similar skills
All skills for Code review and refactoring →ast-grep by other authors comes first.