Agent-Skills.md

Agent Skills: ast-grep

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.

UncategorizedID: trancong12102/agentskills/ast-grep

Repository

trancong12102/agentskills
trancong12102License: MIT
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/trancong12102/agentskills/tree/HEAD/plugins/ora/skills/ast-grep

Skill Files

Browse the full folder contents for ast-grep.

Download Skill

Loading file tree…

plugins/ora/skills/ast-grep/SKILL.md

Skill Metadata

Name
ast-grep
Description
"Structural code tools via ast-grep — search by AST pattern, and outline file/module structure. Use when a search needs code structure that grep can't express (e.g. async functions containing await, calls with specific argument shapes), or when mapping a file's or directory's symbols, exports, and imports before reading it. Do not use for text search when plain grep or LSP suffices."

ast-grep

Search

ast-grep run --pattern 'console.log($ARG)' --lang javascript .        # simple pattern
ast-grep scan --inline-rules "<yaml>" <path>                          # relational/composite rule, no temp file
ast-grep scan --rule /path/rule.yml <path>                            # complex rule from file
echo '<code>' | ast-grep scan --inline-rules "<yaml>" --stdin         # test a rule on a snippet before scanning the codebase
ast-grep run --pattern '<code>' --lang <lang> --debug-query=<style>   # cst = target's full tree (find correct `kind`), ast = named nodes only, pattern = how ast-grep parsed your pattern

Gotchas:

  • Relational rules (inside, has) stop at the first non-matching node unless you add stopBy: end — always add it for deep traversal:

    has:
  pattern: await $EXPR
  stopBy: end

  • Escape metavariables in shell: \$VAR inside double quotes, or single-quote the pattern.

  • Start with a plain pattern; add kind and relational rules only when the pattern alone over- or under-matches. Compose with all/any/not.

Full YAML rule syntax: references/rule-reference.md.

Outline (ast-grep ≥ 0.44, alpha)

Map structure before reading full files — top-level items (functions, classes, imports, exports) and their members, syntax-only, no indexing.

ast-grep outline <file>                                        # local items + member digest
ast-grep outline <dir> --items exports                         # public surface of a directory
ast-grep outline <file> --match Parser --type class --view expanded   # zoom into one symbol, with line numbers
ast-grep outline <dir> --items imports --view signatures       # dependency map
  • --items structure|exports|imports|all; --view names|signatures|digest|expanded in increasing detail. Defaults: file → structure/digest, directory → exports/names.
  • --match <regex> and --type class,enum,... filter top-level items only, never members; --pub-members restricts member views to public members.
  • --json[=stream] for structured output — stream emits one object per file, pipes to jq.