brettatomsbrettatoms/agent-skills/code-symbols/SKILL.md

code-symbols

Skill3 starsChanged 10 months agoMITView on GitHub

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.

Installs packages

In this repository13 other files it gives its agents.
- alpinejsSkill
- browser-toolsSkill
- clojure-replSkill
- clojure-symbolsSkill
- code-renameSkill
- code-searchSkill
- file-navSkill
- githubSkill
- janetSkill
- lib-docsSkill
- plansSkill
- playwrightSkill
- skill-creatorSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Use ast-grep (sg) for structural code search based on tree-sitter parsing.
line 9
Very specific:
Verify: ast-grep --version or sg --version
line 26

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free