Agent-Skills.md

Agent Skills: tree-sitting

AST-powered code navigation via tree-sitter. Auto-scans codebases and provides progressive-disclosure tree views with symbol search, source retrieval, and reference finding. Each invocation is self-contained — no cross-process state. Use when exploring unfamiliar repos, navigating code, or needing fast symbol lookup. Triggers on "map this codebase", "explore repo", "find symbol", "navigate code", "tree-sitter", or when starting work on an unfamiliar repository.

UncategorizedID: oaustegard/claude-skills/tree-sitting

Repository

oaustegard/claude-skills
oaustegardLicense: MIT
1287

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oaustegard/claude-skills/tree/HEAD/tree-sitting

Skill Files

Browse the full folder contents for tree-sitting.

Download Skill

Loading file tree…

tree-sitting/SKILL.md

Skill Metadata

Name
tree-sitting
Description
Symbol-level navigation of a local checkout using tree-sitter ASTs. Answers where a symbol is defined, what lines it spans, which symbols a file exposes, what a directory holds, and where a name is referenced — every answer carries exact line ranges to feed straight into a scoped read. Use for "where is X defined", "who calls X", "find the function/class named", "what's in this file", "give me the line range for", "show me the source of", "list the symbols in", or before editing a file you have not read. Each invocation auto-scans and is self-contained. Not for first-encounter repo orientation (use exploring-codebases), for what a codebase DOES rather than what it contains (featuring), for binding-resolved Python caller sets (searching-codebases), or for literal text and regex matching (plain ripgrep).

tree-sitting

Tree-sitter symbol index over a local checkout. Every result carries line ranges, so the next step is a scoped Read.

Setup

Needs Python 3.10+ and pip install tree-sitter. On macOS, /usr/bin/python3 is 3.9 and will not work; use a Homebrew or uv Python. Grammars are bundled for Linux x86_64 (parsers/*.so) and macOS (parsers/*.dylib).

If a file's grammar doesn't load, the file is skipped and stderr prints WARNING: no grammar for … with the fix. Resolve that before trusting an empty result. On other platforms, run python3 scripts/build_grammars.py (needs git and cc). It writes to $TREESIT_PARSERS_DIR, or ~/.cache/tree-sitting/parsers/ when that is unset, and grammars there take precedence over the bundle. Installed tree-sitter-<lang> wheels are the last fallback.

Use

scripts/treesit.py in this skill's directory scans the repo on every call (cached on disk; invalidated when files or grammars change), prints a tree overview, then answers the queries. Batch queries so one scan serves them all.

python3 scripts/treesit.py REPO                                   # overview, depth 1
python3 scripts/treesit.py REPO --path=src/core --detail=full     # drill in
python3 scripts/treesit.py REPO --no-tree 'find:Parser*' 'source:parse_input' 'refs:ParseState'

| Query | Returns | |---|---| | find:PATTERN[:KIND[:LIMIT]] | symbols by name, substring or glob | | symbols:FILE | every symbol in a file | | source:SYMBOL[:FILE] | the symbol's source | | refs:SYMBOL[:LIMIT] | textual references | | imports:FILE | a file's imports | | dir:PATH | directory overview |

Flags: --depth N (-1 = all), --detail sparse|normal|full, --path DIR, --skip DIRS, --no-tree, --stats, --no-cache, --rebuild-cache. scripts/engine.py exposes CodeCache for use inside one Python process.

Languages: Python, JavaScript, TypeScript/TSX, Go, Rust, Ruby, Java, C, HTML, Markdown (heading outline), Mojo. Other languages get generic extraction if their tree-sitter-<lang> wheel is installed.

Use something else for

  • a repo that isn't on disk: accessing-github-repos
  • what a codebase does: featuring
  • a first look at an unfamiliar repo: exploring-codebases
  • binding-resolved Python callers: searching-codebases --refs
  • literal text or regex: rg