ast-grep

Refactor codebases via structural AST pattern matching and rewriting.

4|2|Updated Jan 30, 2026
One-click install
npx skills add https://github.com/alexanderguy/skills --skill ast-grep-alexanderguy
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ast-grep
Source: https://github.com/alexanderguy/skills/tree/main/skills/ast-grep
Command: npx skills add https://github.com/alexanderguy/skills --skill ast-grep-alexanderguy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It eliminates risky, repetitive manual find-and-replace work by performing large-scale code rewrites based on code structure rather than plain text.

Core Features & Use Cases

  • Structural search and rewrite: Match and transform code using AST patterns that preserve formatting, whitespace, and nesting.
  • Bulk refactors across many files: Apply “rename X to Y” or “change all A-shaped code to B-shaped code” transformations to all call sites and related syntactic positions.
  • Safer matching controls: Prefer ast-grep over blind edits, with language-aware support and guidance on preview-first workflows.

Use cases: Renaming functions, methods, types, or variables across a repository; changing function signatures across implementations and all callers; migrating API usage patterns (including imports) without missing structural variants.

Quick Start

Load the ast-grep skill to rename oldFunction to newFunction across your codebase using structural AST matching instead of manual text edits.

Frequently Asked Questions about ast-grep

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I safely rename functions and update imports across a repository?

To safely rename functions and update imports across a repository, use structural AST pattern matching to rewrite code based on structure rather than plain text. It targets all syntactic positions and call sites while preserving formatting.

What is AST structural search and how does it handle code transformation?

AST structural search matches and transforms code using abstract syntax tree patterns to identify specific syntactic shapes. It applies targeted rewrites while ensuring multi-position correctness through metavariables and YAML relational rules.

What is the best way to migrate API usage patterns without missing variants?

The best way to migrate API usage patterns without missing structural variants is to perform structural AST refactoring. Using language-aware pattern matching with a safe preview-then-apply workflow identifies and updates all matching API implementations across files.

Can I change function signatures across all callers using structural refactoring?

Yes, you can change function signatures across all callers using structural refactoring. Applying AST patterns matches all implementations and related syntactic positions, ensuring bulk refactors apply consistently without manual read-edit-write cycles.

How do I preview structural search refactoring results before applying them?

You preview structural search refactoring results by following a safe preview-then-apply workflow. This process allows you to verify AST pattern matches and targeted transforms across your codebase before committing the bulk rewrites.