code-symbols

by @brettatoms in Development

# Install this skill:

npx skills add brettatoms/agent-skills --skill "code-symbols"

Install specific skill from multi-skill repository

# Description

Find and edit symbols in code using ast-grep (tree-sitter based). Use when finding function definitions, class definitions, symbol usages, renaming symbols, or replacing code in JavaScript, TypeScript, Python, Go, Rust, and other languages. NOT for Clojure - use clj-symbols instead.

# SKILL.md

name: code-symbols
description: Find and edit symbols in code using ast-grep (tree-sitter based). Use when finding function definitions, class definitions, symbol usages, renaming symbols, or replacing code in JavaScript, TypeScript, Python, Go, Rust, and other languages. NOT for Clojure - use clj-symbols instead.
allowed-tools: Bash, Read, Edit, Task

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

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.