# Ast Grep

> Find and safely rewrite Python syntax with ast-grep patterns and rules.

- **Type:** Skill
- **Install:** `agentstack add skill-fmind-dot-ast-grep`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fmind](https://agentstack.voostack.com/s/fmind)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fmind](https://github.com/fmind)
- **Source:** https://github.com/fmind/dot/tree/main/skills/ast-grep
- **Website:** https://fmind.dev

## Install

```sh
agentstack add skill-fmind-dot-ast-grep
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ast-grep

Structural code search and rewrite: a pattern is real code with meta-variables, matched against the syntax tree. A call-expression pattern distinguishes a call from similar text inside a string or comment; string and comment nodes can also be matched deliberately. Use it where `rg` gives false positives; plain text search stays with `rg`.

## Commands

```bash
ast-grep run -p 'print($$$ARGS)' -l python                                      # search; run is the default subcommand
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python             # dry run: prints the diff, changes nothing
ast-grep run -p 'print($$$ARGS)' -r 'logger.info($$$ARGS)' -l python --update-all # apply after reviewing the dry run (-i to confirm per hunk)
ast-grep run -p 'os.getenv($KEY)' -l python --json=compact                       # structured output; --json=stream gives one object per line
ast-grep scan                                                                    # every rule in sgconfig.yml
ast-grep scan -r rules/no-print.yml --format github                              # one rule file; GitHub annotations in CI
```

## Workflow

1. **Write the pattern as code**: `$NAME` matches one node, `$$$NAME` a sequence (arguments, statements), `$_` a node without binding; always pass `-l ` so the pattern parses in the right grammar, and use `--debug-query=ast` when a pattern that should match does not.
1. **Search first**: run without `-r`, read the matches with `-C 2` for context, and tune `--globs` or `--no-ignore` when files are skipped.
1. **Rewrite in two steps**: add `-r` to see the diff, then `--update-all` (or `-i` for an interactive session); captured meta-variables are reused in the replacement.
1. **Promote to a rule**: for a lint or a repeated refactor, `ast-grep new project` scaffolds `sgconfig.yml` and `rules/`; a rule file has `id`, `language`, `rule` (`pattern`, `kind`, `inside`, `has`, `not`), optional `fix`, `severity`, and `message`; `ast-grep test` runs its `valid` and `invalid` cases.
1. **Wire into the gate**: run `ast-grep scan` inside `check:lint` (see [mise](../mise/SKILL.md)) so hooks and CI apply the same rules.

## Gotchas

- **Meta-variables are uppercase**: `$a` is plain text; `$A`, `$ARGS`, `$_` are meta-variables.
- **Pattern must be a complete node**: `foo(` does not parse; match `foo($$$)` and narrow with `--selector`.
- **Rewrite scope**: `-r` replaces the whole matched node, not a substring inside it.
- **Syntax is not name resolution**: inspect imports, aliases, and shadowed names before rewriting; identical syntax can refer to different functions.
- **Language id**: pass `-l python` for inline patterns; under `scan`, the `.py` extension selects the grammar.

## Official Skills

Upstream: `ast-grep/agent-skill`; follow the shared [vendor-skill policy](../agent-project/references/vendor-skills.md) and select the structural-search guidance.

## Documentation

- [ast-grep guide](https://ast-grep.github.io/guide/introduction.html) · [Pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html) · [Rule reference](https://ast-grep.github.io/reference/rule.html) · [Languages](https://ast-grep.github.io/reference/languages.html)
- Releases: [ast-grep](https://github.com/ast-grep/ast-grep/releases) · [changelog](https://github.com/ast-grep/ast-grep/blob/main/CHANGELOG.md)
- Companion skills: [repository-maintenance](../repository-maintenance/SKILL.md) (repository simplification), [python-stack](../python-stack/references/foundation/GUIDE.md) (Python quality gate).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fmind](https://github.com/fmind)
- **Source:** [fmind/dot](https://github.com/fmind/dot)
- **License:** MIT
- **Homepage:** https://fmind.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fmind-dot-ast-grep
- Seller: https://agentstack.voostack.com/s/fmind
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.