ast-grep
Structural code search via ast-grep — use when code shape and element relationships matter, not just text. E.g., "find async functions without error handling", "refactor foo(a, b) to foo({ a, b })". Use Grep for simple name lookups.
How do I install this agent skill?
npx skills add https://github.com/poteto/noodle --skill ast-grepIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The analyzed skill is safe and acts as a documentation/workflow guide for the `ast-grep` tool. It provides instructional details on writing structured code rules, using patterns, atomic rules, and relational conditions without containing executable code blocks, unexpected external dependencies, or malicious behavior.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
2 files scanned · No issues
What does this agent skill do?
ast-grep
Workflow
- Write a test snippet representing the target code
- Write the rule (start with
pattern, escalate tokind+has/insideif needed) - Test with
--stdinbefore searching the codebase - Search the codebase once the rule matches
Critical Gotchas
Always use stopBy: end on relational rules
Without it, has/inside stop at the first non-matching node instead of traversing the full subtree:
# WRONG — will miss deeply nested matches
has:
pattern: await $EXPR
# RIGHT
has:
pattern: await $EXPR
stopBy: end
Escape metavariables in shell
$VAR gets interpreted by the shell. Either escape or single-quote:
# Double-quoted: escape with backslash
ast-grep scan --inline-rules "id: test
language: javascript
rule:
pattern: await \$EXPR" .
# Single-quoted: no escaping needed
ast-grep scan --inline-rules 'id: test
language: javascript
rule:
pattern: await $EXPR' .
Metavariables must be the sole content of an AST node
These don't work: obj.on$EVENT, "Hello $WORLD", a $OP b, $jq
Use $$OP for unnamed nodes (operators, punctuation). Use $$$ARGS for zero-or-more nodes.
Testing with --stdin
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules 'id: test
language: javascript
rule:
kind: function_declaration
has:
pattern: await $EXPR
stopBy: end' --stdin
Debugging with --debug-query
When rules don't match, inspect the AST to find correct kind values:
ast-grep run --pattern 'your code here' --lang javascript --debug-query=cst
Formats: cst (all nodes), ast (named only), pattern (how ast-grep sees your pattern).
Rule syntax
See references/rule_reference.md for the full rule reference (atomic, relational, composite rules, and metavariables).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/poteto/noodle/ast-grep">View ast-grep on skillZs</a>