packages/shared-skills/skills/ast-grep/SKILL.md
sg (also installed as ast-grep) is an AST-aware search and rewrite tool across 25 languages. It treats your pattern as code, parses it the same way it parses your project, and matches structurally. It is the right tool whenever your question depends on code shape rather than text bytes.
This skill ships a Python wrapper at scripts/ast_grep_helper.py and platform install scripts at install.sh (POSIX) and install.ps1 (Windows). The helper adds offline pattern validation, the two-pass write trick, and binary auto-resolution. Use it as your default entry point.
Use it whenever the user's question is about code structure, not bytes:
Request parameter."console.log(x) to logger.info(x)."as any cast."require(...) with import across the repo."Optional[X] to X | None."Switch to plain grep / rg when the question is text-shaped (string literal contents, comments, license headers, file names, cross-language regex). When in doubt, ask: "does the answer depend on the language's syntax tree, or just on the file's bytes?" If the former, ast-grep. If the latter, grep.
The wildcards are $VAR (one AST node) and $$$ (zero or more nodes). Regex syntax fails silently:
| You wrote | What ast-grep saw | What you wanted |
|---|---|---|
foo|bar | bitwise-or of foo and bar | run two separate searches |
.*foo | not parseable | $$$ foo (if $$$ is a list of nodes) or use rg |
\w+ | not parseable | $VAR to capture any identifier |
[a-z] | character class, not parseable | switch to rg |
The full anti-pattern table is in references/pitfalls.md §1. The helper's validate subcommand catches these mechanically — call it before debugging "no matches" by hand.
The pattern itself must parse. def $FN($$$): fails because the trailing : makes it incomplete; use def $FN($$$). function $NAME without params/body fails; use function $NAME($$$) { $$$ }. Full table per language in references/pitfalls.md §2.
--update-all and --json are mutually exclusive (silently)This is the single biggest gotcha when scripting. sg run -p P -r R --json --update-all returns the JSON but does not mutate files. To both preview AND apply, run two passes:
sg run -p P -r R --json=compact . # pass 1: see what would change
sg run -p P -r R --update-all . # pass 2: actually apply
The helper does this automatically when you call replace --apply. Read references/pitfalls.md §9.
scripts/ast_grep_helper.pyA single-file Python 3 stdlib wrapper. Same on every OS. The agent's default entry point.
search — find all matches of a patternpython3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/
Validates the pattern offline first. If the pattern looks like regex (\w, .*, |, etc.) the helper exits with a hint and never calls sg — saves a round-trip. Pass --force to skip validation.
Flags:
--lang ts (or any of the 25 languages; aliases like js, py, rs, kt accepted)--globs '!**/*.test.ts' (repeatable; prefix ! to exclude)-C 3 (context lines)--json-out (raw JSON instead of human format)replace — rewrite by pattern, dry-run by default# Dry-run preview (default — no files mutated)
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/
# Actually apply
python3 scripts/ast_grep_helper.py replace 'console.log($MSG)' 'logger.info($MSG)' --lang ts src/ --apply
The helper:
pattern and rewrite for hint-detectable mistakes.--json=compact to collect matches and show a preview.--apply is set, runs pass 2 with --update-all to mutate files.scan — run YAML rules# Discover sgconfig.yml from cwd and run all rules
python3 scripts/ast_grep_helper.py scan src/
# Run a single rule file
python3 scripts/ast_grep_helper.py scan -r rules/no-console.yml src/
# Apply auto-fixes
python3 scripts/ast_grep_helper.py scan -U src/
# CI-friendly GitHub annotations
python3 scripts/ast_grep_helper.py scan --report-style short src/
validate — offline pattern check (no sg call)Useful for CI lints, pre-commit hooks, and quick sanity checks:
python3 scripts/ast_grep_helper.py validate '\w+' --lang ts
# → exit 2: regex \w not supported. Use $VAR for identifiers.
python3 scripts/ast_grep_helper.py validate 'console.log($MSG)' --lang ts
# → exit 0: pattern looks plausible for ast-grep.
langs / doctor / installpython3 scripts/ast_grep_helper.py langs # list 25 supported languages and aliases
python3 scripts/ast_grep_helper.py doctor # check ast-grep binary availability
python3 scripts/ast_grep_helper.py install # delegate to install.sh / install.ps1
new and test subcommands proxy directly to sg new and sg test.
sg use (when the helper isn't enough)The helper is opinionated. For full control, drop to sg. The skill ships a CLI cheat sheet in references/cli.md. The minimal idioms:
# Search
sg run -p 'console.log($MSG)' --lang ts src/
# Search with JSON for scripting
sg run -p 'console.log($MSG)' --lang ts --json=compact src/ | jq '.[] | .file'
# Rewrite, dry-run
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --json=compact src/
# Rewrite, apply
sg run -p 'console.log($MSG)' -r 'logger.info($MSG)' --lang ts --update-all src/
# Pattern from stdin (great for ad-hoc experiments)
echo 'console.log("hi")' | sg run -p 'console.log($MSG)' --lang js --stdin
# Debug a pattern that returns 0 matches
sg run -p '<your pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample-code>'
# Run YAML rules
sg scan src/
# Inline YAML rule (one-off)
sg scan --inline-rules '
id: no-todo
language: TypeScript
severity: warning
rule: { pattern: TODO }' src/
When using sg directly in a shell, always single-quote patterns so $VAR is not expanded by the shell.
USER asks for "find/rewrite/codemod"
│
├─ structural pattern (function shape, call, class, import, control flow)
│ └→ ast-grep (this skill)
│
├─ text pattern (regex, alternation, character classes, file names)
│ └→ rg / grep
│
├─ semantic question (what variable does this refer to? does this throw?)
│ └→ LSP tools, TypeScript compiler, Pyright, Semgrep with type inference
│
└─ multiple repos / federated search
└→ a search engine + then ast-grep / rg / LSP per-repo
If the user says "find all" or "every", default to ast-grep when the target is shaped (function, class, call, import, statement). Default to rg when the target is text (string content, comment, license header, file name, identifier substring).
A bad pattern silently rewrites the wrong thing. The helper's replace defaults to dry-run for this reason. The flow is:
helper search '<pattern>' --lang X .helper replace '<pattern>' '<rewrite>' --lang X . (no --apply)helper replace '<pattern>' '<rewrite>' --lang X . --apply.Never apply a rewrite that you have not first dry-run.
sg returns 0 matches but you know the code is thereIn priority order:
helper validate '<pattern>' --lang <lang> — catches regex misuse, missing function bodies, Python trailing colons.--lang — sg infers from extension; if you pass a .tsx file with --lang ts (not tsx), JSX won't parse.sg run -p '<pattern>' --lang <lang> --debug-query=ast --stdin <<< '<sample>'. If it shows ERROR nodes, the pattern is malformed.sg run -p '$_' --lang <lang> --debug-query=cst path/to/file | head -40 — find the kind you're trying to match.Do not blindly retry with variations. Each failure has a reason; surface it.
-p patternsUse inline -p when:
Use YAML rules (file under rules/, run via sg scan) when:
constraints, transform, complex inside/has, or composite logic.fix: field).sg test).The full YAML rule schema is in references/yaml-rules.md. Project setup (sgconfig.yml, ruleDirs, utilDirs) is in references/sgconfig.md.
sg run --json=compact produces an array of match objects: { file, range: {start, end}, text, replacement?, lines, language, ... }. Pipe through jq for further processing.--json, sg produces human-readable colored output suitable for terminals.--json-out for raw JSON.replace always summarizes: number of matches, number of files, per-location preview.When summarizing for the user, always include the count of files affected, not just the count of matches. Users care about blast radius.
references/patterns.md — meta-variables, naming rules, strictness levels. Read when you're unsure why a pattern doesn't match.references/pitfalls.md — the failure-mode field guide. Read when 0 matches surprises you.references/recipes.md — copy-paste patterns by language. Read first when you start a new task.references/cli.md — sg run, sg scan, sg test, sg new, sg lsp. Read when the helper isn't enough.references/yaml-rules.md — YAML rule schema. Read when you outgrow inline patterns.references/sgconfig.md — project-level configuration. Read when you set up sg scan for a real project.references/install.md — per-OS install methods. Read only if install.sh / install.ps1 fail.helper validate first. It catches the regex-misuse class of mistakes that account for ~70% of "0 matches" debug sessions.sg run -r ... --update-all without first inspecting the matches. The helper's replace enforces this by default.sg directly to both preview and apply, run two invocations — --json ignores --update-all.'$VAR' not "$VAR". The shell expands $VAR to the empty string in double quotes, breaking the pattern.|, .*, \w, or [a-z], switch to rg instead. Don't try to force ast-grep into a regex shape.--lang is required for stdin. When piping with --stdin, set --lang explicitly; sg cannot infer from extension.ast-grep over sg because sg collides with setgroups. The helper handles this; if you call sg directly, alias it: alias sg=ast-grep.