ast-grep Skill for Claude Code: Structural Code Search

Makes your agent turn a plain-English request into an ast-grep rule, test it on a sample, then search your codebase by code structure.

Installs: 18.4K; on skills.sh
Stars: 900; on GitHub
Files: 1; besides SKILL.md
Updated: Sep 2026; last repo commit

The skill makes your agent search code by its syntax tree. It follows five steps: understand the query, write a small example file, write a rule, test the rule against the example, then run it on the real project. It uses the ast-grep command, with run for simple patterns and scan for rules, and includes tips on the mistakes that cause zero matches.

You must install the ast-grep tool yourself, as the plugin README lists brew, npm and cargo options. The README also says that installing the skill makes it available, not preferred, so name ast-grep in your prompt or add a line to CLAUDE.md or AGENTS.md. Its reference file holds the full rule syntax.

Good for

Developers who need searches plain grep cannot do, such as async functions with no try/catch
Teams auditing a large codebase for a specific code shape
Anyone learning ast-grep rule syntax

Install ast-grep

Claude Code

Copy this prompt.

Install the ast-grep skill in Claude Code. Run this command:

npx skills add https://github.com/ast-grep/agent-skill --skill ast-grep

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.

Sections in SKILL.md

Overview
When to Use This Skill
General Workflow
Step 1: Understand the Query
Step 2: Create Example Code
Step 3: Write the ast-grep Rule
Step 4: Test the Rule
Step 5: Search the Codebase
ast-grep CLI Commands
Inspect Code Structure (--debug-query)
Test Rules (scan with --stdin)
Search with Patterns (run)
Reading --json Output
Search with Rules (scan)
Tips for Writing Effective Rules
Always Use stopBy: end

Key facts

Author: Herrington Darkholme (ast-grep)
Repo: ast-grep/agent-skill, folder ast-grep/skills/ast-grep
Installs on skills.sh: 18,365 as of 2026-11-02
GitHub stars: 900 for the whole ast-grep/agent-skill repo
License: MIT (ast-grep plugin.json)
Last repo commit: 2026-09-13
What is inside: 2 files including SKILL.md; 1 reference file (rule syntax)
skills.sh audits: Gen Agent Trust Hub: pass; Socket: pass; Snyk: pass

What it includes

Understand, example, rule, test, search
Clarify the query, write a sample file, write a rule, test it on the sample, then search the codebase. Debugging steps are listed for rules that match nothing.
Write · Five-step workflow
Simple pattern search
Searches for a single code shape in a language and folder, for example a console.log call. Add --json for output a program can read.
Runs code · ast-grep run --pattern
Search with a rule file
Runs a YAML rule file, which can combine kind, has, inside, all, any and not, over a project.
Runs code · ast-grep scan --rule
Search with a rule written in the command
Runs a rule given directly on the command line. With --stdin it tests a snippet piped in, without creating files.
Runs code · ast-grep scan --inline-rules
Show the syntax tree
Prints the tree in cst, ast or pattern form so the agent can find the right node kinds when a rule matches nothing.
Runs code · --debug-query
stopBy: end and other fixes
Always use stopBy: end on relational rules, start simple and add complexity, use the right rule type, remember patterns match whole nodes, and escape inline rules.
Read · Rule tips
Ready-made example rules
Examples include finding functions with specific content and async functions that lack error handling.
Read · Common use cases
Full rule documentation
A reference for rule syntax that the agent opens when it needs more than the examples.
Read · references/rule_reference.md

From the official docs

Permissions

Low risk

The agent runs the ast-grep command over your code and writes small temporary test files. The commands listed are searches, so review any command that adds other options before you approve it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

You install ast-grep separately
The skill does not install the ast-grep tool. Install it with the method in the plugin README, which the agent will not do for you.
The plugin route adds a second skill
The README's marketplace route installs the ast-grep plugin, whose folder holds this skill and an ast-grep-outline skill. The plugin.json lists a name, version, author and license, and no hooks or servers.

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No switch. The commands in SKILL.md are searches (run and scan), and the agent also writes small temporary test files.
Scopes	Runs the ast-grep command on your project folders Writes temporary test files such as test_example.js and test_rule.yml

Questions

What does the ast-grep skill do?

It makes your agent search your code by structure, not by text. It turns a request such as "find async functions without error handling" into an ast-grep rule and tests it before searching.

How do I install it?

Use the install box at the top of this page. The repo README also offers a plugin marketplace route for Claude Code, and the plugin folder holds a second skill, ast-grep-outline, so that route adds two skills. You also need the ast-grep command itself, which the README says you can install with brew, npm or cargo.

Does it need an API key?

No. SKILL.md names no API key or account. It needs the ast-grep command installed on your machine.

Why does my agent still use plain grep?

The README explains that installing the skill makes it discoverable but not preferred, because the agent also has a text search tool. Name ast-grep in your prompt, or add a line about it to your CLAUDE.md or AGENTS.md.

Does it change my code?

SKILL.md describes search commands, run and scan. It does write small temporary test files, so check where the agent saves them.

Is it safe?

It runs a local command-line tool over your files and writes test files. Read each command it proposes, and keep the temporary files out of your commits.

Information

updated Nov 2, 2026

Repository: ast-grep/agent-skill
Folder: ast-grep/skills/ast-grep

ast-grep/agent-skill skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

ast-grep SKILL.md · github.com
ast-grep/agent-skill README · github.com
ast-grep plugin.json · github.com
ast-grep rule_reference.md · github.com
ast-grep on skills.sh · skills.sh
ast-grep/agent-skill · github.com