Agent-Skills.md

Agent Skills: short form when sg is installed:

Use ast-grep for syntax-aware structural code search, analysis, linting, and safe rewrite planning. Load this when a task asks to find code by shape/AST, refactor repeated code patterns, inspect function/component/import usage structurally, write ast-grep rules, or when ripgrep would be too imprecise.

UncategorizedID: wunki/dotfiles/ast-grep

Repository

wunki/dotfiles
wunki
466

Install this agent skill to your local

pnpm dlx add-skill https://github.com/wunki/dotfiles/tree/HEAD/agents/skills/ast-grep

Skill Files

Browse the full folder contents for ast-grep.

Download Skill

Loading file tree…

agents/skills/ast-grep/SKILL.md

Skill Metadata

Name
ast-grep
Description
Use ast-grep for syntax-aware structural code search, analysis, linting, and safe rewrite planning. Load this when a task asks to find code by shape/AST, refactor repeated code patterns, inspect function/component/import usage structurally, write ast-grep rules, or when ripgrep would be too imprecise.

Use ast-grep (sg) when the task depends on code structure: calls, imports, functions, components, conditionals, object literals, nested constructs, or safe repeated rewrites.

Prefer rg for plain text/content search.

Default commands

Check availability:

ast-grep --version || sg --version

Search by AST pattern:

ast-grep run --lang <language> -p '<pattern>' [path]
# short form when sg is installed:
sg run --lang <language> -p '<pattern>' [path]

Use JSON when output may be parsed or large:

ast-grep run --lang ts -p 'console.log($$$ARGS)' --json=stream

Preview rewrites before applying:

ast-grep run --lang js -p 'var $NAME = $VALUE' -r 'let $NAME = $VALUE'
ast-grep run --lang js -p 'var $NAME = $VALUE' -r 'let $NAME = $VALUE' --update-all

Only use --update-all after inspecting the preview.

Pattern reminders

  • Patterns should look like real source code in the target language.
  • $A captures one AST node.
  • $$$ARGS captures zero or more nodes.
  • Always set --lang explicitly (js, ts, jsx, tsx, json, yaml, python, go, rust, etc.).
  • Quote patterns with single quotes to avoid shell expansion.
  • If a pattern fails unexpectedly, inspect it with --debug-query=ast.

Common patterns

# console calls
ast-grep run --lang ts -p 'console.log($$$ARGS)'

# function declarations
ast-grep run --lang ts -p 'function $NAME($$$ARGS) { $$$BODY }'

# React hook usage
ast-grep run --lang tsx -p 'useEffect($$$ARGS)'

# imports from a package
ast-grep run --lang ts -p 'import { $$$IMPORTS } from "$PKG"'

# YAML key/value shape
ast-grep run --lang yaml -p '$KEY: $VALUE'

Rule workflow

For complex searches or reusable rules:

  1. Start from a small code example that should match.
  2. Write the simplest working -p pattern first.
  3. Add YAML rule constraints only after the basic pattern works.
  4. Use --json=stream and/or --debug-query=ast to inspect matches.
  5. If it fails, remove constraints and debug one condition at a time.
  6. Preview rewrites; apply only after reviewing matches.

Docs to fetch when needed

  • AI prompting: https://ast-grep.github.io/advanced/prompting.html
  • LLM docs: https://ast-grep.github.io/llms-full.txt
  • Pattern syntax: https://ast-grep.github.io/guide/pattern-syntax.html
  • Rule config: https://ast-grep.github.io/guide/rule-config.html
  • JSON output: https://ast-grep.github.io/guide/tools/json.html
  • Rewrite code: https://ast-grep.github.io/guide/rewrite-code.html
  • CLI reference: https://ast-grep.github.io/reference/cli.html