code-yeongyu/oh-my-openagent / packages/shared-skills/skills/ast-grep
ast-grep
UnverifiedSearches 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.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 343 B |
| AGENTS.md | markdown | 3.1 KB |
| LICENSE | other | 1.0 KB |
| README.md | markdown | 7.7 KB |
| SKILL.md | skill md | 13.6 KB |
| SOURCE | other | 125 B |
| install.ps1 | script | 7.2 KB |
| install.shexecutable | script | 7.5 KB |
| references/cli.md | markdown | 7.2 KB |
| references/install.md | markdown | 5.7 KB |
| references/patterns.md | markdown | 5.8 KB |
| references/pitfalls.md | markdown | 9.0 KB |
| references/recipes.md | markdown | 8.2 KB |
| references/sgconfig.md | markdown | 6.3 KB |
| references/yaml-rules.md | markdown | 11.2 KB |
| scripts/ast_grep_helper.pyexecutable | script | 26.8 KB |
| tests/smoke.ps1 | script | 5.6 KB |
| tests/smoke.shexecutable | script | 7.6 KB |
AGENTS.md
View on GitHub# 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`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |