agentleFS
D-SheyD-Shey/autoharness/.agents/skills/ast-grep/SKILL.md

ast-grep

Skill10 starsChanged yesterdayMITView on GitHub

Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.

23 other projects use a version of this, 10 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use rust, create-pr and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    rust

    Use this guide when working on Rust changes in the FAST monorepo.

    Also in 3 projects that use this

  • SentrySkill

    create-pr

    Create pull requests following Sentry conventions. Use when opening PRs, writing PR descriptions, or preparing changes for review. Follows Sentry's code review guidelines.

    Also in 4 projects that use this

  • GoogleSkill

    tdd

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    Also in 4 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 5 projects that use this

  • +1 more from getsentry

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 12 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when users:

    line 14
  2. Distinctive:

    Ask to search for code with particular AST characteristics

    line 18
  3. Distinctive:

    Follow this process to help users write effective ast-grep rules:

    line 23
  4. Distinctive:

    Write a simple code snippet that represents what the user wants to match.

    line 35
  5. Distinctive:

    If searching for "async functions that use await", create a test file:

    line 38
  6. Very specific:

    Always use stopBy: end for relational rules (inside, has) to ensure search goes to the end of the direction

    line 53
  7. Very specific:

    Use pattern for simple structures

    line 54
  8. Very specific:

    Use kind with has/inside for complex structures

    line 55
  9. Distinctive:

    Use ast-grep CLI to verify the rule matches the example code.

    line 73
  10. Very specific:

    Add stopBy: end to relational rules if not present

    line 93
  11. Very specific:

    Use --debug-query to understand the AST structure (see below)

    line 94
  12. Very specific:

    Check if kind values are correct for the language

    line 95
  13. Distinctive:

    Test a rule against code snippet without creating files:

    line 157
  14. Distinctive:

    When you don't need relational rules (inside/has)

    line 189
  15. Distinctive:

    When you need the power of full YAML rules

    line 241
  16. Very specific:

    If that doesn't work, try kind to match the node type

    line 263
  17. Very specific:

    Add relational rules (has, inside) as needed

    line 264
  18. Distinctive:

    When rules don't match:

    line 275
  19. Very specific:

    Use --debug-query=cst to see the actual AST structure

    line 276
  20. Distinctive:

    Check if metavariables are being detected correctly

    line 277
  21. Very specific:

    Verify the node kind matches what you expect

    line 278
  22. Distinctive:

    Ensure relational rules are searching in the right direction

    line 279
  23. Very specific:

    When using --inline-rules, escape metavariables in shell commands:

    line 290
  24. Very specific:

    Use \$VAR instead of $VAR (shell interprets $ as variable)

    line 291
  25. Very specific:

    When a rule still fails after --debug-query and the rule reference, read the official docs:

    line 359

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ast-grep Code Search

Overview

This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.

When to Use This Skill

Use this skill when users:

  • Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
  • Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
  • Request searches that require understanding code structure rather than just text
  • Ask to search for code with particular AST characteristics
  • Need to perform complex code queries that traditional text search cannot handle

General Workflow

Follow this process to help users write effective ast-grep rules:

Step 1: Understand the Query

Clearly understand what the user wants to find. Ask clarifying questions if needed:

  • What specific code pattern or structure are they looking for?
  • Which programming language?
  • Are there specific edge cases or variations to consider?
  • What should be included or excluded from matches?

Step 2: Create Example Code

Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.

Example: If searching for "async functions that use await", create a test file:

// test_example.js
async function example() {
  const result = await fetchData();
  return result;
}

Step 3: Write the ast-grep Rule

Translate the pattern into an ast-grep rule. Start simple and add complexity as needed.

Key principles:

  • Always use stopBy: end for relational rules (inside, has) to ensure search goes to the end of the direction
  • Use pattern for simple structures
  • Use kind with has/inside for complex structures
  • Break complex queries into smaller sub-rules using all, any, or not

Example rule file (test_rule.yml):

id: async-with-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end

See references/rule_reference.md for comprehensive rule documentation.

Step 4: Test the Rule

Use ast-grep CLI to verify the rule matches the example code. There are two main approaches:

Option A: Test with inline rules (for quick iterations)

echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules "id: test
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" --stdin

Option B: Test with rule files (recommended for complex rules)

ast-grep scan --rule test_rule.yml test_example.js

Debugging if no matches:

  1. Simplify the rule (remove sub-rules)
  2. Add stopBy: end to relational rules if not present
  3. Use --debug-query to understand the AST structure (see below)
  4. Check if kind values are correct for the language
  5. For zero matches from run --pattern (not rules), see the "Zero Matches?" tip below

Step 5: Search the Codebase

Once the rule matches the example code correctly, search the actual codebase:

For simple pattern searches:

ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project

For complex rule-based searches:

ast-grep scan --rule my_rule.yml /path/to/project

For inline rules (without creating files):

ast-grep scan --inline-rules "id: my-rule
language: javascript
rule:
  pattern: \$PATTERN" /path/to/project

ast-grep CLI Commands

Inspect Code Structure (--debug-query)

Dump the AST structure to understand how code is parsed:

ast-grep run --pattern 'async function example() { await fetch(); }' \
  --lang javascript \
  --debug-query=cst

Available formats:

  • cst: Concrete Syntax Tree (shows all nodes including punctuation)
  • ast: Abstract Syntax Tree (shows only named nodes)
  • pattern: Shows how ast-grep interprets your pattern

Use this to:

  • Find the correct kind values for nodes
  • Understand the structure of code you want to match
  • Debug why patterns aren't matching

Example:

# See the structure of your target code
ast-grep run --pattern 'class User { constructor() {} }' \
  --lang javascript \
  --debug-query=cst

# See how ast-grep interprets your pattern
ast-grep run --pattern 'class $NAME { $$$BODY }' \
  --lang javascript \
  --debug-query=pattern

Test Rules (scan with --stdin)

Test a rule against code snippet without creating files:

echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test
language: javascript
rule:
  pattern: await \$EXPR" --stdin

Add --json for structured output:

echo "const x = await fetch();" | ast-grep scan --inline-rules "..." --stdin --json

Search with Patterns (run)

Simple pattern-based search for single AST node matches:

# Basic pattern search
ast-grep run --pattern 'console.log($ARG)' --lang javascript .

# Search specific files
ast-grep run --pattern 'class $NAME' --lang python /path/to/project

# JSON output for programmatic use
ast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .

When to use:

  • Simple, single-node matches
  • Quick searches without complex logic
  • When you don't need relational rules (inside/has)

Reading --json Output

--json prints a bare JSON array of matches (no matches wrapper). For pattern foo($ARG, $$$REST):

[{
  "text": "foo(\"value\", 1, 2)",
  "file": "src/app.js",
  "range": { "start": { "line": 41, "column": 10 }, "end": { "line": 41, "column": 27 } },
  "metaVariables": {
    "single": { "ARG": { "text": "\"value\"" } },
    "multi": { "REST": [ { "text": "1" }, { "text": "2" } ] }
  }
}]

scan --json uses the same schema.

(Each match also includes lines and language.) range.start.line is 0-based. Named metavariables ($ARG) land in single, list metavariables ($$$REST) in multi as a list (empty if nothing captured). Extract with jq:

ast-grep run --pattern 'foo($ARG)' --lang javascript --json . \
  | jq -r '.[] | "\(.file):\(.range.start.line + 1): \(.metaVariables.single.ARG.text)"'

Search with Rules (scan)

YAML rule-based search for complex structural queries:

# With rule file
ast-grep scan --rule my_rule.yml /path/to/project

# With inline rules
ast-grep scan --inline-rules "id: find-async
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" /path/to/project

# JSON output
ast-grep scan --rule my_rule.yml --json /path/to/project

When to use:

  • Complex structural searches
  • Relational rules (inside, has, precedes, follows)
  • Composite logic (all, any, not)
  • When you need the power of full YAML rules

Tip: For relational rules (inside/has), always add stopBy: end to ensure complete traversal.

Tips for Writing Effective Rules

Always Use stopBy: end

For relational rules, always use stopBy: end unless there's a specific reason not to:

has:
  pattern: await $EXPR
  stopBy: end

This ensures the search traverses the entire subtree rather than stopping at the first non-matching node.

Start Simple, Then Add Complexity

Begin with the simplest rule that could work:

  1. Try a pattern first
  2. If that doesn't work, try kind to match the node type
  3. Add relational rules (has, inside) as needed
  4. Combine with composite rules (all, any, not) for complex logic

Use the Right Rule Type

  • Pattern: For simple, direct code matching (e.g., console.log($ARG))
  • Kind + Relational: For complex structures (e.g., "function containing await")
  • Composite: For logical combinations (e.g., "function with await but not in try-catch")

Debug with AST Inspection

When rules don't match:

  1. Use --debug-query=cst to see the actual AST structure
  2. Check if metavariables are being detected correctly
  3. Verify the node kind matches what you expect
  4. Ensure relational rules are searching in the right direction

Zero Matches? Patterns Match Whole AST Nodes

run --pattern matches complete AST nodes, not text substrings, so zero matches can mean "code absent" or "pattern has the wrong node shape":

  • Qualified paths are whole nodes: env::var($ENV) does NOT match std::env::var("X"). Try both bare and fully-qualified forms, or use $$$ to absorb extra intermediate nodes.
  • To tell them apart: test the pattern on a snippet known to contain the code, and inspect how ast-grep parsed it with --debug-query=pattern (works for run, not just scan/rules). For zero matches from rules instead, follow the Step 4 debugging checklist.

Escaping in Inline Rules

When using --inline-rules, escape metavariables in shell commands:

  • Use \$VAR instead of $VAR (shell interprets $ as variable)
  • Or use single quotes: '$VAR' works in most shells

Example:

# Correct: escaped $
ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" .

# Or use single quotes
ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .

Common Use Cases

Find Functions with Specific Content

Find async functions that use await:

ast-grep scan --inline-rules "id: async-await
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: await \$EXPR
        stopBy: end" /path/to/project

Find Code Inside Specific Contexts

Find console.log inside class methods:

ast-grep scan --inline-rules "id: console-in-class
language: javascript
rule:
  pattern: console.log(\$\$\$)
  inside:
    kind: method_definition
    stopBy: end" /path/to/project

Find Code Missing Expected Patterns

Find async functions without try-catch:

ast-grep scan --inline-rules "id: async-no-trycatch
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: await \$EXPR
        stopBy: end
    - not:
        has:
          pattern: try { \$\$\$ } catch (\$E) { \$\$\$ }
          stopBy: end" /path/to/project

Resources

references/

Contains detailed documentation for ast-grep rule syntax:

  • rule_reference.md: Comprehensive ast-grep rule documentation covering atomic rules, relational rules, composite rules, and metavariables

Load these references when detailed rule syntax information is needed.

Online documentation

When a rule still fails after --debug-query and the rule reference, read the official docs:

  • https://ast-grep.github.io/llms.txt indexes every docs page; fetch the one page you need (each is linked as a .md file, such as https://ast-grep.github.io/guide/rule-config/relational-rule.md).
  • https://ast-grep.github.io/llms-full.txt holds all the docs in one file of about 850 KB. Download it and search it; never read it whole.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.