Code Symbols Skill

Use ast-grep (sg) for structural code search based on tree-sitter parsing. Works with 31 languages.

Important: Clojure is NOT supported. Use the clj-symbols skill for Clojure code.

Prerequisites

# npm
npm install --global @ast-grep/cli

# Homebrew
brew install ast-grep

# Cargo
cargo install ast-grep --locked

Verify: ast-grep --version or sg --version

Supported Languages

Category	Languages
Web	JavaScript, TypeScript, HTML, CSS, JSON
Systems	C, C++, Go, Rust
Scripting	Python, Ruby, PHP, Lua, Bash
JVM	Java, Kotlin, Scala
Other	Swift, Haskell, Elixir, Nix

Not supported: Clojure, Erlang, R, MATLAB

Quick Reference

Task	Command
Find pattern	ast-grep run --pattern 'PATTERN' --lang LANG path/
Find with JSON	ast-grep run --pattern 'PATTERN' --lang LANG path/ --json
Rename symbol	ast-grep run --pattern 'old' --rewrite 'new' --lang LANG path/ --update-all

Pattern Syntax

Patterns must be valid code that tree-sitter can parse.

Meta-Variables

Syntax	Meaning	Example
$NAME	Match single node	function $NAME() {}
$$$	Match zero or more nodes	function foo($$$)
$_	Match but don't capture	$_($$$)

Basic Examples

# Match any function call
ast-grep run --pattern '$FUNC($$$)' --lang js path/

# Match specific function
ast-grep run --pattern 'myFunction($$$)' --lang js path/

# Match variable assignment
ast-grep run --pattern 'const $NAME = $VALUE' --lang js path/

Common Operations

Find Function Definition

# JavaScript
ast-grep run --pattern 'function $NAME($$$) { $$$ }' --lang js path/

# Python
ast-grep run --pattern 'def $NAME($$$):' --lang py path/

# Go
ast-grep run --pattern 'func $NAME($$$)' --lang go path/

Find Symbol Usages

ast-grep run --pattern 'myFunction($$$)' --lang js path/
ast-grep run --pattern '$OBJ.myMethod($$$)' --lang js path/

Rename Symbol

# Preview
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/

# Apply
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/ --update-all

# Interactive
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/ --interactive

JSON Output

ast-grep run --pattern '$FUNC($$$)' --lang js path/ --json

Parse with jq:

ast-grep run --pattern 'function $NAME($$$) { $$$ }' --lang js path/ --json \
  | jq '.[] | {name: .metaVariables.single.NAME.text, file, line: .range.start.line}'

When to Use ast-grep vs ripgrep

Scenario	Tool
Find by name (text pattern)	ripgrep (rg)
Find by structure (function, class)	ast-grep
Language-specific patterns	ast-grep
Maximum speed	ripgrep
Accurate symbol boundaries	ast-grep

Additional References

• Language patterns: See references/languages.md for JS, TS, Python, Go, Rust patterns
• Editing: See references/editing.md for rewrite, rename, and YAML rules
• Workflows: See references/workflows.md for common workflows