ast-grep agent skill
ast-grep skills for Claude Code: the agent writes and tests structural AST search rules and builds a compact map of a codebase
- 899 ★ on the repository
- Last commit
Extended access
Why this level
- The agent saves an example to a temporary file and runs ast-grep commands over your code
- The skill lets the agent search and show source fragments from the whole project
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/ast-grep-agent-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent saves an example to a temporary file and runs ast-grep commands over your code
- The skill lets the agent search and show source fragments from the whole project
This is third-party code. Review the repository files before installing.
What it does
The repository is a Claude Code plugin marketplace with an ast-grep plugin of two skills. The `ast-grep` skill turns a plain-language request ("find async functions without error handling") into an ast-grep rule. The agent clarifies the task, writes example code, drafts a rule, tests it on the example and only then searches the whole project, showing files and lines. The `outline` skill runs `ast-grep outline` and returns a compact map of a file or directory with imports, functions, classes and their members, so code can be read in stages. ast-grep itself is installed separately.
Who it is for. For developers who need search by code structure where grep is noisy, and who work with Claude Code.
Good fit when
- You need every async function that uses await, or those left without try/catch
- You want setState calls inside useEffect
- Before a migration you need a list of places that call deprecated functions
- An agent needs a file map before editing: `ast-grep outline <file>`
- You need functions with more than three parameters or console.log calls with several arguments
Not a fit when
- ast-grep is not installed and you do not want to install it: the skill writes rules and runs the command, the program itself is not in it
- You need plain text search: it is faster and needs no installation
- You want an MCP server with an AST dump: the README points to a separate ast-grep-mcp
- You are interested in the tool itself: ast-grep has its own card in the catalog
Example request
Use ast-grep to find all async functions in the project that contain await but no try/catchLimitations
ast-grep must be installed (brew install ast-grep, npm install -g @ast-grep/cli or cargo install ast-grep). Installing the skill makes it discovered, not preferred: the agent still has plain text search, so either say "use ast-grep" or pin the preference in AGENTS.md or CLAUDE.md. A run with no matches exits successfully, so "nothing found" and "wrong pattern" look alike. The repository has no LICENSE file; plugin.json and the README state MIT.
How to disable. Disable or remove the ast-grep plugin in the /plugin menu. If you installed with npx skills, delete the skill folders from the agent's skills directory. ast-grep itself is removed with the package manager you installed it with.
FAQ
How do I install the ast-grep skill in Claude Code?
Run npx skills add ast-grep/agent-skill, or add the marketplace with /plugin marketplace add ast-grep/agent-skill and install with /plugin install ast-grep. ast-grep itself must be installed separately.
How do I make the agent pick ast-grep instead of text search?
Name the tool in the request ("use ast-grep to find...") or state once in AGENTS.md or CLAUDE.md that syntax-dependent search should default to ast-grep --lang <language> -p '<pattern>'.
Why did the search find nothing?
A run with no matches exits successfully, so the pattern may be the cause. Ask the agent to show the rule and the code's AST. Loading llms-full.txt with the ast-grep documentation and using ast-grep-mcp to test patterns on a snippet both help.
How is the skill different from ast-grep itself?
ast-grep searches and rewrites code by its syntax tree. The skill teaches the agent to draft and test rules for it and does not contain the program.
What does the outline skill do?
It calls ast-grep outline and returns a map of a file or directory with line numbers: imports, functions, classes and their members. That is cheaper than reading whole sources.
Discussion
No questions or reviews yet.
Related
SkillsStructural code search, lint and rewrite on the syntax tree, with patterns written like ordinary code
14 skills that find the gaps in a task before the code: interviews, plans, assumption tests and proof that a bug fix works
Context Engine: code search and memory for an agent
Context Engine
A skill that teaches an agent to query the Context Engine code index and symbol graph before reading files directly
Softaworks Agent Toolkit
Softaworks Agent Skills
A marketplace of skills, subagents and commands for coding agents: development, documentation, planning and workplace communication
Semantic code search and call graphs for agents, fully local. MCP mode connects the search to Claude Code and Cursor
A Claude Code and Codex plugin with skills for code research, tests, refactoring and independent review of finished changes
README in short
The README explains that the repository holds a plugin with a structural search skill and lists the requirement: an installed ast-grep. It continues with three install routes, example queries, the agent's six working steps, supported languages and key features such as metavariables, relational queries and logical combinations. It ends with tips for debugging empty results, the repository layout and a support section.
README badge
Original SKILL.md
---
name: ast-grep
description: 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.
---
# ast-grep Code Search
## Overview
This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.
## When to Use This Skill
Use this skill when users:
- Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
- Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
- Request searches that require understanding code structure rather than just text
- Ask to search for code with particular AST characteristics
- Need to perform complex code queries that traditional text search cannot handle
## General Workflow
Follow this process to help users write effective ast-grep rules:
### Step 1: Understand the Query
Clearly understand what the user wants to find. Ask clarifying questions if needed:
- What specific code pattern or structure are they looking for?
- Which programming language?
- Are there specific edge cases or variations to consider?
- What should be included or excluded from matches?
### Step 2: Create Example Code
Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.
**Example:**
If searching for "async functions that use await", create a test file:
```javascript
// test_example.js
async function example() {
const result = await fetchData();
return result;
}