Agent skill

treesitter-patterns

Universal patterns for tree-sitter code parsing. Covers AST visitors, query patterns, and language plugin development. Framework-agnostic.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/consiliency/treesitter-patterns

SKILL.md

Tree-sitter Patterns Skill

Universal patterns for working with tree-sitter in any project. Covers AST parsing, query patterns, visitors, and language plugin development.

Design Principle

This skill is framework-generic. It provides universal tree-sitter patterns:

  • NOT tailored to Code-Index-MCP, treesitter-chunker, or any specific project
  • Covers common patterns applicable across all tree-sitter projects
  • Project-specific queries go in project-specific skills

Variables

Variable Default Description
TREE_SITTER_DIR tree_sitter Directory for language parsers
QUERY_DIR queries Directory for .scm query files
LANGUAGES auto Auto-detect or list of languages

Instructions

MANDATORY - Follow the Workflow steps below in order.

  1. Identify languages to parse
  2. Install appropriate language parsers
  3. Write queries for extraction needs
  4. Handle edge cases and errors

Red Flags - STOP and Reconsider

If you're about to:

  • Parse without error handling (syntax errors are common)
  • Assume all files parse successfully
  • Write queries without testing on sample code
  • Ignore performance for large files

STOP -> Add error handling -> Test on edge cases -> Then proceed

Cookbook

Language Plugin Development

  • IF: Creating a new language parser
  • THEN: Read and execute ./cookbook/language-plugin.md

AST Visitor Patterns

  • IF: Walking the AST to extract information
  • THEN: Read and execute ./cookbook/ast-visitor.md

Query Patterns

  • IF: Writing tree-sitter queries
  • THEN: Read and execute ./cookbook/query-patterns.md

Quick Reference

Python Setup

python
import tree_sitter_python as tspython
from tree_sitter import Language, Parser

# Create parser
parser = Parser(Language(tspython.language()))

# Parse code
source = b"def hello(): pass"
tree = parser.parse(source)

# Access root node
root = tree.root_node
print(root.sexp())

Node Navigation

python
# Get children
for child in node.children:
    print(child.type, child.text)

# Named children only (skip punctuation)
for child in node.named_children:
    print(child.type)

# Find by type
def find_all(node, type_name):
    results = []
    if node.type == type_name:
        results.append(node)
    for child in node.children:
        results.extend(find_all(child, type_name))
    return results

functions = find_all(root, "function_definition")

Query Language

scheme
; Match function definitions
(function_definition
  name: (identifier) @function.name
  parameters: (parameters) @function.params
  body: (block) @function.body)

; Match class definitions
(class_definition
  name: (identifier) @class.name
  body: (block) @class.body)

; Match imports
(import_statement
  (dotted_name) @import.module)

; Match decorated functions
(decorated_definition
  (decorator) @decorator
  definition: (function_definition
    name: (identifier) @function.name))

Running Queries

python
from tree_sitter import Query

query = Query(Language(tspython.language()), """
(function_definition
  name: (identifier) @name
  body: (block) @body)
""")

captures = query.captures(root)
for node, name in captures:
    print(f"{name}: {node.text.decode()}")

Common Node Types

Language Functions Classes Imports
Python function_definition class_definition import_statement
JavaScript function_declaration class_declaration import_statement
TypeScript function_declaration class_declaration import_statement
Go function_declaration type_declaration import_declaration
Rust function_item impl_item use_declaration

Error Handling

python
def safe_parse(source: bytes) -> tuple[Tree | None, list[str]]:
    """Parse with error collection."""
    tree = parser.parse(source)
    errors = []

    def collect_errors(node):
        if node.type == "ERROR" or node.is_missing:
            errors.append(f"Error at {node.start_point}: {node.text[:50]}")
        for child in node.children:
            collect_errors(child)

    collect_errors(tree.root_node)
    return tree, errors

tree, errors = safe_parse(source)
if errors:
    print(f"Parse errors: {errors}")

Visitor Pattern

python
from abc import ABC, abstractmethod

class ASTVisitor(ABC):
    """Base visitor for tree-sitter AST."""

    def visit(self, node):
        method_name = f"visit_{node.type}"
        visitor = getattr(self, method_name, self.generic_visit)
        return visitor(node)

    def generic_visit(self, node):
        for child in node.named_children:
            self.visit(child)

    @abstractmethod
    def visit_function_definition(self, node):
        pass

class FunctionExtractor(ASTVisitor):
    def __init__(self):
        self.functions = []

    def visit_function_definition(self, node):
        name_node = node.child_by_field_name("name")
        if name_node:
            self.functions.append(name_node.text.decode())
        self.generic_visit(node)

extractor = FunctionExtractor()
extractor.visit(tree.root_node)
print(extractor.functions)

Performance Tips

  1. Incremental parsing: For edits, use parser.parse(new_source, old_tree)
  2. Lazy evaluation: Don't traverse entire tree if you only need specific nodes
  3. Query optimization: Use more specific queries to reduce matches
  4. Memory management: Large files can use significant memory
  5. Batch processing: Process multiple files in parallel

Integration

With Code Analysis

python
def analyze_file(path: Path) -> CodeAnalysis:
    source = path.read_bytes()
    tree = parser.parse(source)

    return CodeAnalysis(
        functions=extract_functions(tree),
        classes=extract_classes(tree),
        imports=extract_imports(tree),
        complexity=calculate_complexity(tree)
    )

With BAML

baml
class CodeStructure {
  functions FunctionInfo[]
  classes ClassInfo[]
  imports string[]
}

class FunctionInfo {
  name string
  parameters string[]
  return_type string?
  line_start int
  line_end int
}

Best Practices

  1. Error tolerance: Always handle parse errors gracefully
  2. Use queries: Prefer queries over manual traversal
  3. Test on real code: Test with actual codebases, not just samples
  4. Document node types: Reference language grammar for node types
  5. Version parsers: Pin tree-sitter language versions

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results