Skip to main content
affpapa.org
RU EN
skill CX Codex

ast-grep · pproenca — Claude Code skill: write and debug AST rules

A skill with community best practices for writing, reviewing and debugging ast-grep rules for code search, linting and rewriting.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill ast-grep -a claude-code
Open on GitHub

What ast-grep does

The skill covers how to write ast-grep YAML rules and how to debug the ones that don't match. It ships 46 rules in 8 categories ordered by impact: pattern correctness, meta variables, rule composition, constraints, rewrites, project organisation, performance and testing. Each rule lives in its own file under references/.

The workflow is short. Clarify what you're looking for, write a sample snippet, then build the rule. Use pattern for simple structures, kind with has or inside for complex ones, and combine them with all, any or not. Debugging goes through ast-grep run --pattern '[code]' --lang [language] --debug-query=ast, and an inline rule can be tested on stdin with ast-grep scan --inline-rules.

One thing breaks searches more than anything else: relational rules with inside or has need stopBy: end, otherwise the subtree walk stops early and matches go missing. In inline rules for the shell, escape \$VAR or wrap the rule in single quotes. The skill installs as a file in your agent's skills directory and doesn't bundle the CLI — you still need ast-grep on the machine.

What it helps with

  • write a YAML rule that matches a construct by AST
  • fix a pattern that misses the code it should find
  • set up linting with automatic fixes
  • split ast-grep rules into files across a project
  • speed up searches on a large codebase

Example prompts for the agent

  • Write an ast-grep rule that finds every console.log call in src
  • Why doesn't this rule match my code? Check the AST with --debug-query=ast
  • Build a rule with inside and has to find methods inside a class

How to install ast-grep

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill ast-grep -a claude-code

2Manually: put the files in place

~/.claude/skills/ast-grep/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ast-grep/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ast-grep

How do I install ast-grep in Claude?

Run npx skills add pproenca/dot-skills --skill ast-grep -a claude-code. The skill lands at ~/.claude/skills/ast-grep/SKILL.md.

What does ast-grep do?

It's a skill with practices for writing ast-grep rules: searching the syntax tree, linting and rewriting code. It helps the agent author and debug YAML rules.

How is ast-grep different from plain text search?

Rules match AST nodes instead of lines, so they respect the language's syntax. That's what kind, has, inside and meta variables are for.

Source text

SKILL.md · MIT 
---
name: ast-grep
description: ast-grep rule writing and usage best practices. This skill should be used when writing, reviewing, or debugging ast-grep rules for code search, linting, and transformation. Triggers on tasks involving YAML rules, pattern syntax, meta variables, constraints, or code rewriting.
---

# ast-grep Community Best Practices

Comprehensive best practices guide for ast-grep rule writing and usage, maintained by the ast-grep community. Contains 46 rules across 8 categories, prioritized by impact to guide automated rule generation and code transformation.

## When to Apply

Reference these guidelines when:
- Writing new ast-grep rules for linting or search
- Debugging patterns that don't match expected code
- Optimizing rule performance for large codebases
- Setting up ast-grep projects with proper organization
- Reviewing ast-grep rules for correctness and maintainability

## General Workflow

Follow this workflow when creating ast-grep rules for code search:

### Step 1: Understand the Query

Clarify what you want to find:
- Target programming language
- Edge cases to handle
- What to include vs exclude

### Step 2: Create Example Code

Write a sample code snippet representing the desired match pattern.

### Step 3: Write the ast-grep Rule

Choose the right approach:
- Use `pattern` for simple structures
- Use `kind` with `has`/`inside` for complex structures
- Combine with `all`, `any`, or `not` for compound queries
- **Always use `stopBy: end` for relational rules** (`inside`, `has`) to ensure complete search

### Step 4: Test the Rule

```bash
# Inspect AST structure
ast-grep run --pattern '[code]' --lang [language] --debug-query=ast

# Test inline rule
echo "[code]" | ast-grep scan --inline-rules "[rule]" --stdin

# Test from file
ast-grep scan --rule [file.yml] [path]
```

### Step 5: Search the Codebase

Deploy the validated rule:
```bash
# Search with pattern (simple matches)
ast-grep run --pattern '[pattern]' --lang [language] [path]

# Search with rule file (complex queries)
ast-grep scan --rule [file.yml] [path]

# Apply fixes interactively
ast-grep scan --rule [file.yml] --interactive [path]
```

### Quick Tips

1. **Always use `stopBy: end`** - Ensures complete subtree traversal for relational rules
2. **Start simple, add complexity** - Begin with patterns, progress to kinds, then relational rules
3. **Debug with AST inspection** - Use `--debug-query=ast` to verify structure matching
4. **Escape in inline rules** - Use `\$VAR` or single quotes for shell commands
5. **Test in playground first** - Use https://ast-grep.github.io/playground.html for rapid iteration

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Pattern Correctness | CRITICAL | `pattern-` |
| 2 | Meta Variable Usage | CRITICAL | `meta-` |
| 3 | Rule Composition | HIGH | `compose-` |
| 4 | Constraint Design | HIGH | `const-` |
| 5 | Rewrite Correctness | MEDIUM-HIGH | `rewrite-` |
| 6 | Project Organization | MEDIUM | `org-` |
| 7 | Performance Optimization | MEDIUM | `perf-` |
| 8 | Testing & Debugging | LOW-MEDIUM | `test-` |

## Quick Reference

### 1. Pattern Correctness (CRITICAL)

- [`pattern-valid-syntax`](references/pattern-valid-syntax.md) - Use valid parseable code as patterns
- [`pattern-language-aware`](references/pattern-language-aware.md) - Account for language-specific syntax differences
- [`pattern-context-selector`](references/pattern-context-selector.md) - Use context and selector for code fragments
- [`pattern-avoid-comments-strings`](references/pattern-avoid-comments-strings.md) - Avoid matching inside comments and strings
- [`pattern-strictness-levels`](references/pattern-strictness-levels.md) - Configure pattern strictness appropriately
- [`pattern-kind-vs-pattern`](references/pattern-kind-vs-pattern.md) - Choose kind or pattern based on specificity needs
- [`pattern-debug-ast`](references/pattern-debug-ast.md) - Use debug query to inspect AST structure
- [`pattern-nthchild-matching`](references/pattern-nthchild-matching.md) - Use nthChild for index-based positional matching
- [`pattern-range-matching`](references/pattern-range-matching.md) - Use range for character position matching

### 2. Meta Variable Usage (CRITICAL)

- [`meta-naming-convention`](references/meta-naming-convention.md) - Follow meta variable naming conventions
- [`meta-single-node`](references/meta-single-node.md) - Match single AST nodes with meta variables
- [`meta-reuse-binding`](references/meta-reuse-binding.md) - Reuse meta variables to enforce equality
- [`meta-underscore-noncapture`](references/meta-underscore-noncapture.md) - Use underscore prefix for non-capturing matches
- [`meta-named-vs-unnamed`](references/meta-named-vs-unnamed.md) - Use double dollar for unnamed node matching
- [`meta-multi-match-lazy`](references/meta-multi-match-lazy.md) - Understand multi-match variables are lazy

### 3. Rule Composition (HIGH)

- [`compose-all-for-and-logic`](references/compose-all-for-and-logic.md) - Use all for AND logic between rules
- [`compose-any-for-or-logic`](references/compose-any-for-or-logic.md) - Use any for OR logic between rules
- [`compose-not-for-exclusion`](references/compose-not-for-exclusion.md) - Use not for exclusion patterns
- [`compose-inside-for-context`](references/compose-inside-for-context.md) - Use inside for contextual matching
- [`compose-has-for-children`](references/compose-has-for-children.md) - Use has for child node requirements
- [`compose-matches-for-reuse`](references/compose-matches-for-reuse.md) - Use matches for rule reusability
- [`compose-precedes-follows`](references/compose-precedes-follows.md) - Use precedes and follows for sequential positioning
- [`compose-field-targeting`](references/compose-field-targeting.md) - Use field to target specific sub-nodes

### 4. Constraint Design (HIGH)

- [`const-kind-filter`](references/const-kind-filter.md) - Use kind constraints to filter meta variables
- [`const-regex-filter`](references/const-regex-filter.md) - Use regex constraints for text patterns
- [`const-not-inside-not`](references/const-not-inside-not.md) - Avoid constraints inside not rules
- [`const-pattern-constraint`](references/const-pattern-constraint.md) - Use pattern constraints for structural filtering
- [`const-post-match-timing`](references/const-post-match-timing.md) - Understand constraints apply after matching

### 5. Rewrite Correctness (MEDIUM-HIGH)

- [`rewrite-preserve-semantics`](references/rewrite-preserve-semantics.md) - Preserve program semantics in rewrites
- [`rewrite-meta-variable-reference`](references/rewrite-meta-variable-reference.md) - Reference all necessary meta variables in fix
- [`rewrite-transform-operations`](references/rewrite-transform-operations.md) - Use transform for complex rewrites
- [`rewrite-test-before-deploy`](references/rewrite-test-before-deploy.md) - Test rewrites on representative code
- [`rewrite-syntax-validity`](references/rewrite-syntax-validity.md) - Ensure fix templates produce valid syntax

### 6. Project Organization (MEDIUM)

- [`org-project-structure`](references/org-project-structure.md) - Use standard project directory structure
- [`org-unique-rule-ids`](references/org-unique-rule-ids.md) - Use unique descriptive rule IDs
- [`org-severity-levels`](references/org-severity-levels.md) - Assign appropriate severity levels
- [`org-file-filtering`](references/org-file-filtering.md) - Use file filtering for targeted rules
- [`org-message-clarity`](references/org-message-clarity.md) - Write clear actionable messages

### 7. Performance Optimization (MEDIUM)

- [`perf-specific-patterns`](references/perf-specific-patterns.md) - Use specific patterns over generic ones
- [`perf-stopby-boundaries`](references/perf-stopby-boundaries.md) - Use stopBy to limit search depth
- [`perf-thread-parallelism`](references/perf-thread-parallelism.md) - Leverage parallel scanning with threads
- [`perf-avoid-regex-heavy`](references/perf-avoid-regex-heavy.md) - Avoid heavy regex in hot paths

### 8. Testing & Debugging (LOW-MEDIUM)

- [`test-valid-invalid-cases`](references/test-valid-invalid-cases.md) - Write both valid and invalid test cases
- [`test-snapshot-updates`](references/test-snapshot-updates.md) - Use snapshot testing for fix verification
- [`test-playground-first`](references/test-playground-first.md) - Test patterns in playground first
- [`test-edge-cases`](references/test-edge-cases.md) - Test edge cases and boundary conditions

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Full Compiled Document

- [AGENTS.md](AGENTS.md) - Complete compiled guide with all rules

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

ast-grep by other authors comes first.

ast-grep ast-grep This skill helps turn code-search requests into ast-grep rules. Use it when you need to find code by its structure rather than by matching text. CX Codex +1 17,900installs ast-grep-find parcadei Runs AST-based code search and refactoring using language syntax trees. Helps locate and replace function calls, imports, and variables without matching text inside strings or comments. CX Codex +1 518installs codegraph-ast-grep stark-ai-de Installs and repairs CodeGraph plus ast-grep so your coding agent gets semantic repo scope and structural syntax evidence. CX Codex +1 2,700installs ast-grep-outline ast-grep Generates a compact syntax map of code files, imports, and exports with line numbers before reading raw source files. CX Codex +1 2,400installs file-search Netresearch DTT GmbH A skill that points your agent at rg, fd, ast-grep, semgrep, rga, tokei and scc instead of grep and find. Useful for gathering context before a task. CX Codex +1 521installs dart-best-practices kevmoo Enforces idiomatic Dart code style and formatting during generation and review. Focuses on clean multi-line string literals and strict 80-character line wrapping. CX Codex +1 832installs typescript-clean-code bmad-labs A skill for reviewing and refactoring TypeScript: code smell catalogs, four detection layers, and step-by-step workflows. CX Codex +1 628installs

From the same set45

nginx-c-module-design A skill for anyone writing nginx C modules: it helps you decide what to expose as directives, how to name them and where they belong. Most useful while the module's config interface is still being shaped. CX Codex +1 352installs nginx-c-modules A skill that feeds your agent 49 rules for nginx C module work: pool memory, request lifecycle, config merging. Useful when you write or refactor a handler, filter or upstream. CX Codex +1 349installs dockerfile-optimise A skill with 48 rules from official Docker docs: layer caching, multi-stage builds, security. Useful when writing or refactoring Dockerfiles. CX Codex +1 344installs uniwind A skill with 45+ rules for Uniwind, the Tailwind bindings for React Native. Useful when setting up a project, building themes or migrating from NativeWind. CX Codex +1 341installs 37signals-rails A rule set for Ruby on Rails the 37signals way: vanilla Rails, CRUD controllers, rich domain models, Hotwire. Useful when you write or refactor code and want to stay in that school. CX Codex +1 329installs mui-base A skill with 48 rules for building headless React component libraries the MUI Base UI way. Useful when logic and styling stay apart. CX Codex +1 328installs vhs A skill with 47 rules for VHS .tape files, so your agent writes and reviews terminal recordings that turn into GIFs and videos. CX Codex +1 323installs unix-cli A rule set that steers your AI agent when it writes or reviews command-line tools: flags, exit codes, output streams. CX Codex +1 319installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor