How do I install the Ast Grep skill?

Run npx skillmds@latest add banteg/ast-grep 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.

Is Ast Grep safe to use?

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.

Which AI agents work with Ast Grep?

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.

Is Ast Grep free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Ast Grep?

banteg (@banteg) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Ast Grep by banteg — Agent Skill

Name: Ast Grep
Author: banteg

Ast Grep

Use ast-grep (`sg`) for Python and Zig structural code exploration, mechanical codemods, and rule maintenance in this repo. Use this when you need syntax-aware search/replace (instead of regex), to add/update ast-grep rules in `tools/ast-grep/`, or to verify rule behavior with `sg scan` and `sg test`. For Zig, use `sgconfig.local.yml` so the custom parser is loaded.

banteg 37a2edd 2 files · 3.0 KB Updated Sep 17, 2026

File contents

Ast-grep

Prefer sg for structural exploration and mechanical rewrites in Python/Zig code.

Quick Start

Run policy checks: sg scan
Run rule tests + snapshots: sg test
Run full local check chain: just check
For Zig parsing/local Zig rules: add -c sgconfig.local.yml

Structural Exploration

Use sg run with -p for ad-hoc structural queries.

Python examples:

sg run -l python -p 'config.data.get($$$ARGS)' src tests
sg run -l python -p 'except Exception: pass' src tests

Zig examples (must use local config):

sg run -c sgconfig.local.yml -l zig -p '@intFromFloat(@round(_DT * 1000.0))' crimson-zig/src
sg run -c sgconfig.local.yml -l zig -p 'const _NAME = _TYPE{};' crimson-zig/src

Zig metavariables use _VAR style in patterns (for example _EXPR, _TYPE).

Mechanical Codemods

Start narrow (single directory or file set).
Prototype match/rewrite:

sg run -l python -p 'config.data.get($$$ARGS)' -r 'config.get($$$ARGS)' src

Apply intentionally:

Interactive: add -i
Apply all matches: add -U

Review git diff and rerun sg scan and sg test.

For Zig typed-empty-init codemods, reuse the existing recipe:

just zig-z004-fix

Repo Rule Layout

Main config: sgconfig.yml
Main rules: tools/ast-grep/rules/
Main tests: tools/ast-grep/tests/
Local config: sgconfig.local.yml
Local rules: tools/ast-grep/rules-local/
Local tests: tools/ast-grep/tests-local/
Shared utils: tools/ast-grep/utils/

Rules are YAML files with id, language, severity, message, path scope (files/ignores), and rule matcher. Keep id, rule filename, and test filename aligned.

Repo Test Layout

Each test file mirrors a rule ID and includes:

valid: examples that must not match
invalid: examples that must match

Snapshot files live in __snapshots__/ beside tests and are checked by sg test.

Useful commands:

# all configured tests
sg test

# one rule by id regex
sg test -f no-config-data-get

# include local Zig tests/rules config
sg test -c sgconfig.local.yml

# refresh all snapshots after intentional rule changes
sg test -U

Repo Policy Notes

From CONTRIBUTING.md:

Prefer ast-grep over regex-only edits for structural transforms.
For Zig, use sgconfig.local.yml to load the custom parser.
When mistakes repeat, encode them as rules/tests/snapshots.

---name: ast-grepdescription: Use ast-grep (`sg`) for Python and Zig structural code exploration, mechanical codemods, and rule maintenance in this repo. Use this when you need syntax-aware search/replace (instead of regex), to add/update ast-grep rules in `tools/ast-grep/`, or to verify rule behavior with `sg scan` and `sg test`. For Zig, use `sgconfig.local.yml` so the custom parser is loaded.---# Ast-grepPrefer `sg` for structural exploration and mechanical rewrites in Python/Zig code.## Quick Start- Run policy checks: `sg scan`- Run rule tests + snapshots: `sg test`- Run full local check chain: `just check`- For Zig parsing/local Zig rules: add `-c sgconfig.local.yml`## Structural ExplorationUse `sg run` with `-p` for ad-hoc structural queries.Python examples:```bashsg run -l python -p 'config.data.get($$$ARGS)' src testssg run -l python -p 'except Exception: pass' src tests```Zig examples (must use local config):```bashsg run -c sgconfig.local.yml -l zig -p '@intFromFloat(@round(_DT * 1000.0))' crimson-zig/srcsg run -c sgconfig.local.yml -l zig -p 'const _NAME = _TYPE{};' crimson-zig/src```Zig metavariables use `_VAR` style in patterns (for example `_EXPR`, `_TYPE`).## Mechanical Codemods1. Start narrow (single directory or file set).2. Prototype match/rewrite:```bashsg run -l python -p 'config.data.get($$$ARGS)' -r 'config.get($$$ARGS)' src```3. Apply intentionally:- Interactive: add `-i`- Apply all matches: add `-U`4. Review `git diff` and rerun `sg scan` and `sg test`.For Zig typed-empty-init codemods, reuse the existing recipe:```bashjust zig-z004-fix```## Repo Rule Layout- Main config: `sgconfig.yml`- Main rules: `tools/ast-grep/rules/`- Main tests: `tools/ast-grep/tests/`- Local config: `sgconfig.local.yml`- Local rules: `tools/ast-grep/rules-local/`- Local tests: `tools/ast-grep/tests-local/`- Shared utils: `tools/ast-grep/utils/`Rules are YAML files with `id`, `language`, `severity`, `message`, path scope (`files`/`ignores`), and `rule` matcher. Keep `id`, rule filename, and test filename aligned.## Repo Test LayoutEach test file mirrors a rule ID and includes:- `valid`: examples that must not match- `invalid`: examples that must matchSnapshot files live in `__snapshots__/` beside tests and are checked by `sg test`.Useful commands:```bash# all configured testssg test# one rule by id regexsg test -f no-config-data-get# include local Zig tests/rules configsg test -c sgconfig.local.yml# refresh all snapshots after intentional rule changessg test -U```## Repo Policy NotesFrom `CONTRIBUTING.md`:- Prefer ast-grep over regex-only edits for structural transforms.- For Zig, use `sgconfig.local.yml` to load the custom parser.- When mistakes repeat, encode them as rules/tests/snapshots.

Frequently asked questions