| Filename | Latest commit message | Latest commit date |
|---|---|---|
| ast-grep | ||
| ast-grep.zip | ||
| README.md | ||
ast-grep Skill for Claude Code
A Claude Code skill that enables powerful structural code search using Abstract Syntax Tree (AST) patterns. Search your codebase based on code structure rather than just text matching.
What is This?
Agent Skills are modular capabilities that extend Claude’s functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.
ast-grep skill teaches Claude how to write and use ast-grep rules to perform advanced code searches. Unlike traditional text-based search (grep, ripgrep), ast-grep understands the structure of your code, allowing you to find patterns like:
- "Find all async functions that don't have error handling"
- "Locate all React components that use a specific hook"
- "Find functions with more than 3 parameters"
- "Search for console.log calls inside class methods"
Prerequisites
You need to have ast-grep installed on your system:
# macOS
brew install ast-grep
# npm
npm install -g @ast-grep/cli
# cargo
cargo install ast-grep
Verify installation:
ast-grep --version
Installation
- Clone or download this repository to your Claude Code skills directory:
# If you have a skills directory configured
cp -r ast-grep ~/.claude/skills/
# Or place it wherever your Claude Code skills are located
-
The skill should be automatically detected by Claude Code. You can verify by checking available skills in Claude Code.
-
You will need to ask Claude to use this skill explicitly in your queries, like "Use ast-grep to find...". Claude code, as of Nov 2025, cannot pick up ast-grep for proper use cases automatically.
How to Use
Once installed, simply ask Claude to search your code using structural patterns. Claude will automatically use this skill when appropriate.
Example Queries
Find async functions with await:
Find all async functions in this project that use await
Find missing error handling:
Show me async functions that don't have try-catch blocks
Find specific function calls:
Find all places where we call console.log with more than one argument
Find code in specific contexts:
Find all setState calls inside useEffect hooks
How It Works
When you ask Claude to search for code patterns:
- Claude analyzes your query and determines if ast-grep is appropriate
- It creates example code that matches your search criteria
- It writes an ast-grep rule to match the pattern
- It tests the rule against the example code
- Once verified, it searches your entire codebase
- Results are presented with file paths and line numbers
Supported Languages
ast-grep supports many programming languages including:
- JavaScript/TypeScript
- Python
- Rust
- Go
- Java
- C/C++
- Ruby
- PHP
- And many more
Key Features
- Structure-aware search: Matches code based on AST structure, not just text
- Metavariables: Use
$VARto match any expression, statement, or identifier - Relational queries: Find code inside specific contexts (e.g., "find X inside Y")
- Composite logic: Combine rules with AND, OR, NOT operations
- Test-driven approach: Rules are tested before running on your codebase
Advanced Usage
Direct ast-grep Commands
While Claude will handle most use cases automatically, you can also use ast-grep directly:
# Simple pattern search
ast-grep run --pattern 'console.log($ARG)' --lang javascript .
# Complex rule-based search
ast-grep scan --inline-rules "id: my-rule
language: javascript
rule:
kind: function_declaration
has:
pattern: await \$EXPR
stopBy: end" .
Debugging
If a search isn't working as expected, ask Claude to:
- Show you the ast-grep rule it created
- Inspect the AST structure of your code
- Test the rule against example code
Files in This Skill
SKILL.md- Main skill instructions for Claudereferences/rule_reference.md- Comprehensive ast-grep rule documentationREADME.md- This file
Tips for Best Results
- Be specific: The more details you provide, the better the search results
- Provide examples: If possible, show Claude an example of what you want to find
- Iterate: Start with a broad search and narrow it down
- Ask for explanations: Ask Claude to explain the ast-grep rule it creates
Examples of What You Can Search For
Code Quality
- Functions without return statements
- Functions with too many parameters
- Unused variables
- Missing null checks
Patterns
- React hooks usage patterns
- API call patterns
- Database query patterns
- Error handling patterns
Refactoring
- Find all uses of deprecated functions
- Locate code that needs migration
- Find inconsistent patterns across codebase
Security
- Potential SQL injection points
- Unsafe eval usage
- Missing input validation
Troubleshooting
Claude isn't using the skill:
- Make sure ast-grep is installed (
ast-grep --version) - Try being more explicit: "Use ast-grep to search for..."
No results found:
- Try a simpler query first
- Ask Claude to show you the rule and test it
- Provide an example of code you want to match
Unexpected results:
- Refine your query with more details
- Ask Claude to exclude certain patterns
- Request to see the AST structure of your code
Contributing
To improve this skill:
- Edit
SKILL.mdto update Claude's instructions - Add examples to
references/directory - Test with various code patterns
Resources
- ast-grep Official Documentation
- ast-grep Playground - Test patterns online
- ast-grep GitHub
License
This skill follows ast-grep's MIT license for any included documentation or examples.
Support
For issues with:
- This skill: Open an issue in this repository
- ast-grep itself: Visit ast-grep GitHub
- Claude Code: Check Claude Code documentation