ast-grep — Claude Code skill for structural code search
This skill helps turn code-search requests into ast-grep rules. Use it when you need to find code by its structure rather than by matching text.
npx skills add ast-grep/agent-skill --skill ast-grep -a claude-codeWhat ast-grep does
The skill translates a plain-language request into an ast-grep rule. It starts by clarifying the language and the structures to include or exclude, then suggests testing the rule against a small code example. Complex queries can combine YAML rules such as pattern, kind, has, inside, all, any, and not.
Test a rule with ast-grep scan, then search a project with ast-grep run or ast-grep scan. The guide also covers inspecting parsed code with --debug-query and reading --json results. You need the ast-grep CLI installed; without it, the command-line checks in the guide cannot run.
What it helps with
- find async functions without error handling
- locate function calls with specific arguments
- match language constructs by AST structure
- test a search rule against a code snippet
Example prompts for the agent
- Find async functions without error handling in this project and write an ast-grep rule for them.
- Locate JavaScript calls to `fetchData` with these arguments.
- Test this ast-grep rule against the snippet and explain why it returns no matches.
How to install ast-grep
1Skills CLI (Vercel)
npx skills add ast-grep/agent-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 ast-grep/agent-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 ast-grep/agent-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 ast-grep/agent-skill ast-grep2Manually: put the files in place
.github/skills/ast-grep/SKILL.md1Skills CLI (Vercel)
npx skills add ast-grep/agent-skill --skill ast-grep -a gemini-cli2Platform CLI
gemini skills install https://github.com/ast-grep/agent-skill --path ast-grep/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 ast-grep/agent-skill --skill ast-grep -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Similar
Questions about ast-grep
How do I install ast-grep in Claude Code?
Run npx skills add ast-grep/agent-skill --skill ast-grep -a claude-code. This installs the skill for Claude Code.
What does the ast-grep skill do?
It helps write and test structural search rules, then apply them to a codebase with the ast-grep CLI.
What do I need to test ast-grep rules?
The guide uses the ast-grep CLI. You can test a rule on a snippet with scan --stdin or run it against files and a project.
