Skip to content

code-yeongyu/oh-my-openagent / packages/shared-skills/skills/ast-grep

ast-grep

Unverified

Searches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg.

FileKindSize
.gitignoreother343 B
AGENTS.mdmarkdown3.1 KB
LICENSEother1.0 KB
README.mdmarkdown7.7 KB
SKILL.mdskill md13.6 KB
SOURCEother125 B
install.ps1script7.2 KB
install.shexecutablescript7.5 KB
references/cli.mdmarkdown7.2 KB
references/install.mdmarkdown5.7 KB
references/patterns.mdmarkdown5.8 KB
references/pitfalls.mdmarkdown9.0 KB
references/recipes.mdmarkdown8.2 KB
references/sgconfig.mdmarkdown6.3 KB
references/yaml-rules.mdmarkdown11.2 KB
scripts/ast_grep_helper.pyexecutablescript26.8 KB
tests/smoke.ps1script5.6 KB
tests/smoke.shexecutablescript7.6 KB
# ast-grep — Vendored Structural-Search Skill

**Generated:** 2026-08-24 (f3642fcda)

## OVERVIEW

Vendored skill teaching agents ast-grep (`sg`) structural search/rewrite, plus a stdlib-Python helper CLI that wraps the `sg` binary. Upstream pin in `SOURCE`: upstream `code-yeongyu/ast-grep-skill @ 3148c69` (ast-grep 0.45.0), "vendored as a sync; do not fork-drift". Earned this file: own executable surface (749-LOC helper + installers + smoke tests) and a no-fork-drift upstream contract that has no analogue elsewhere in `shared-skills`.

## STRUCTURE

```
ast-grep/
├── SKILL.md / README.md          # agent workflow / user overview
├── SOURCE                        # upstream pin — the no-fork-drift contract
├── scripts/ast_grep_helper.py    # 749-LOC stdlib CLI (argparse; no deps)
├── install.sh / install.ps1      # macOS/Linux + Windows installers
├── references/                   # cli, install, patterns, pitfalls, recipes, yaml-rules (510 LOC), sgconfig
└── tests/smoke.{sh,ps1}          # POSIX + PowerShell smoke (also shell syntax + content checks)
```

## HELPER CLI (`scripts/ast_grep_helper.py`)

Subcommands: `search`, `replace` (dry-run; `--apply` to write), `scan`, `test`, `new`, `langs`, `doctor`, `install`, `validate`. Resolves the `sg`/`ast-grep` binary across PATH, Homebrew, npm, and OMO caches, validates patterns before executing, and shells out — it never links ast-grep as a library. Internal handlers `cmd_*`; utilities `validate_pattern`, `normalize_lang`, `resolve_binary`, `run_sg`. Nothing in-repo imports it; docs and skills invoke it by path. `omo-opencode/src/cli/install-ast-grep-sg.ts` locates this skill dir to install the binary.

## CONVENTIONS

- AST patterns, never regex, for syntax-shaped queries; `$VAR` singles, `$$$` multis; patterns must parse as complete code in the target language.
- Two-pass rewrites: preview with `--json=compact`, apply separately with `--update-all` — the flags are mutually exclusive in `sg`.
- `sgconfig.yml` discovered upward; `ruleDirs`, optional `testConfigs`/`utilDirs`, language globs, custom languages, injections.
- Upstream syncs land as whole vendored refreshes matching `SOURCE`; local edits ride along until the next sync absorbs or reverts them.

## ANTI-PATTERNS

- NO regex constructs (`.*`, `.+`, `\w`, `\d`, literal `|`) inside AST patterns — that is the skill's #1 pitfall.
- No incomplete patterns (e.g. Python `def $F($$$):` without a body).
- NEVER `--apply` a rewrite without the dry-run preview first.
- Text/comment/byte queries go to `rg`, not structural matching.
- Do not fork-drift from the `SOURCE` pin; a sync is a vendored refresh, not a merge.

## COMMANDS

```bash
# from packages/shared-skills/skills/ast-grep/
python3 scripts/ast_grep_helper.py search '<PATTERN>' [path] --lang <LANG>
python3 scripts/ast_grep_helper.py replace '<PATTERN>' '<REWRITE>' --lang ts   # dry-run; add --apply
python3 scripts/ast_grep_helper.py doctor
bash tests/smoke.sh          # or: pwsh tests/smoke.ps1
# direct:  sg run -p '<PATTERN>' --lang ts path
```

- Parent (source checkout only, not shipped with the installed skill): `packages/shared-skills/AGENTS.md`.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall