Always set --lang explicitly for predictable parsing.
Start with search-only patterns before rewrite mode.
Review every rewrite in git diff before staging.
Common Pitfalls
Binary name is sg, not ast-grep.
$VAR matches one node; $$$VARS matches multiple nodes.
Parse failures in malformed files can hide expected matches.
Output Interpretation
Default output includes file and location for each match.
--json returns structured match objects with range and bindings.
Why It Matters For Agents
Enables safe refactors that understand syntax nesting and boundaries.
Greatly reduces false positives compared with regex replacements.
Repo Conventions
Prefer ast-grep over text replacement for semantic code edits.
Keep rewrite patterns narrow and validated against sample files.
Trigger Examples
Should trigger: "Replace all Python print(...) calls with logger calls structurally."
Should trigger: "Find functions missing docstrings by syntax pattern."
Should not trigger: "Download a binary release artifact over HTTP."
1---2name: tool-ast-grep-23description: tool-ast-grep4---5# tool-ast-grep67## When To Use89- Perform syntax-aware code search where regex is too noisy.10- Apply structural refactors with AST-level metavariables.11- Match multi-line language constructs safely.1213## Trusted Commands1415```bash16sg --pattern 'console.log($ARG)' --lang ts17sg --pattern 'useEffect($FN, [])' --lang tsx src/18sg --pattern 'console.log($ARG)' --rewrite 'logger.info($ARG)' --lang ts19sg --pattern '$X' --rewrite '$Y' --lang ts --interactive20sg --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python21sg --json --pattern 'print($$$ARGS)' --lang python .22```2324## Safe Defaults2526- Always set `--lang` explicitly for predictable parsing.27- Start with search-only patterns before rewrite mode.28- Review every rewrite in git diff before staging.2930## Common Pitfalls3132- Binary name is `sg`, not `ast-grep`.33- `$VAR` matches one node; `$$$VARS` matches multiple nodes.34- Parse failures in malformed files can hide expected matches.3536## Output Interpretation3738- Default output includes file and location for each match.39- `--json` returns structured match objects with range and bindings.4041## Why It Matters For Agents4243- Enables safe refactors that understand syntax nesting and boundaries.44- Greatly reduces false positives compared with regex replacements.4546## Repo Conventions4748- Prefer ast-grep over text replacement for semantic code edits.49- Keep rewrite patterns narrow and validated against sample files.5051## Trigger Examples5253- Should trigger: "Replace all Python `print(...)` calls with logger calls structurally."54- Should trigger: "Find functions missing docstrings by syntax pattern."55- Should not trigger: "Download a binary release artifact over HTTP."
Run npx skillmds@latest add niksavis/tool-ast-grep-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
tool-ast-grep It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
niksavis (@niksavis) published this skill. Their other Agent Skills are listed on their SkillMD profile.
niksavis