Agent-Skills.md

Agent Skills: ast-grep (sg)

Effective code search, analysis, and refactoring using ast-grep (sg). Use this skill for precise AST-based code modifications, structural search, and linting.

UncategorizedID: OutlineDriven/odin-claude-plugin/ast-grep

Repository

OutlineDriven/odin-claude-plugin
OutlineDrivenLicense: Apache-2.0
9

Install this agent skill to your local

pnpm dlx add-skill https://github.com/OutlineDriven/odin-claude-plugin/tree/HEAD/skills/ast-grep

Skill Files

Browse the full folder contents for ast-grep.

Download Skill

Loading file tree…

skills/ast-grep/SKILL.md

Skill Metadata

Name
ast-grep
Description
Effective code search, analysis, and refactoring using ast-grep (sg). Use this skill for precise AST-based code modifications, structural search, and linting.

ast-grep (sg)

ast-grep is a fast and polyglot tool for code searching, linting, and rewriting based on Abstract Syntax Trees (AST). It excels at structural search and replace where regex fails.

When to use

  • Structural Search: Finding code based on structure (e.g., "all function calls to foo with 2 arguments") regardless of whitespace.
  • Refactoring: Renaming variables, changing function signatures, or transforming code patterns safely.
  • Linting: Creating custom rules to enforce code style or best practices.
  • Code Analysis: Extracting information from codebases.

Quick Start

CLI Basics

# Search (pattern must be in single quotes)
ast-grep -p '$A + $B' --lang ts

# Rewrite (dry run)
ast-grep -p '$A != null' --rewrite '$A' --lang ts

# Interactive Rewrite
ast-grep -p 'var $A = $B' --rewrite 'const $A = $B' --interactive

Pattern Syntax

  • Meta-variables: $VAR matches any single node.
  • Multi-meta-variables: $$$ARGS matches zero or more nodes (list of items).
  • Wildcard: $_ matches any node (non-capturing).
  • Anonymous: $$ matches any list of nodes (non-capturing).

See Pattern Syntax for details.

Core Concepts

Understanding Named vs Unnamed nodes and Matching Strictness is crucial for precise patterns.

  • Named Nodes: identifier, function_definition (matched by $VAR).
  • Unnamed Nodes: (, ), ; (skipped by default in smart mode).
  • Strictness: Control matching precision (smart, cst, ast, relaxed, signature).

See Core Concepts for details.

Rule Configuration (YAML)

For complex tasks, use YAML configuration files.

id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$ARGS)
  inside:
    kind: function_declaration
    stopBy: end
fix: '' # Remove the log

See Rule Configuration for details.

Advanced Rewriting

ast-grep supports complex transformations (regex replace, case conversion) and rewriters for sub-node transformation.

See Rewriting & Transformations for details.

Project Setup & Testing

For larger projects, organize rules and tests using sgconfig.yml.

  • Scaffold: ast-grep new project
  • Config: sgconfig.yml defines rule and test directories.
  • Testing: Define valid and invalid cases to ensure rule accuracy.

See Project Setup & Testing for details.

Utility Rules

Reuse logic with local or global utility rules. Enables recursive matching.

utils:
  is-literal:
    any: [{kind: string}, {kind: number}]
rule:
  matches: is-literal

See Utility Rules for details.

Configuration Reference

Full reference for YAML fields (id, severity, files, ignores) and supported languages.

See Configuration Reference for details.

CLI Reference

Common commands: scan, run, new, test, lsp.

See CLI Reference for details.