Install
npx skills add ast-grep/agent-skillWho it is for
Use this skill when you want a programming assistant to search by code structure (abstract syntax tree), not just text matching. Officially it sits in the Claude Code plugin marketplace and provides ast-grep structural search.
Prerequisites: ast-grep is already installed on this machine, and the assistant can install skills. The guide does not say how to install ast-grep itself; do not invent an installer. The guide names Claude Code; do not treat other clients as official exclusives. Whether anything outside that named set can use it is not stated.
There is only one install path: a single npx command. After install you must explicitly ask to use the skill in the prompt, for example "Use ast-grep to find...". The guide says that as of November 2025, Claude Code still cannot automatically decide to use ast-grep in every suitable situation. The guide does not name a destination directory; after install, only confirm in the current assistant that the skill can be invoked by name.
First try in 3 minutes
Official page:
https://github.com/ast-grep/agent-skill
First confirm that local ast-grep works, then run the recommended install (it writes skill files to this machine; verify the repository name first):
npx skills add ast-grep/agent-skill
If the command fails, stop. After success, do not change application code first. Open an existing repository and say clearly in natural language: Use ast-grep to find..., plus a low-risk structural target, for example finding a certain function-call shape. Ask the assistant to first judge whether ast-grep is a fit, write examples and rules for matching, and test on the examples first.
Success signal: the assistant explicitly used ast-grep, the rule was verified on the examples, and whole-repository results include file paths and line numbers. If it wants to write a rule file or change application code, stop it first and confirm side effects before continuing.
Usage examples
Example 1: read-only structural search. The prompt must explicitly name ast-grep. Have the assistant find matches by structure and return file paths and line numbers. On the first pass, only look at the results; do not let it refactor along the way. The guide does not give a language scope or sample repository; do not infer from an imagined language list.
Example 2: write the rule first, verify it, then search the whole repository. The steps in the guide are: analyze whether the query fits ast-grep, create sample code for matching, write the rule, test it on the sample, search the whole codebase only after that passes, then report paths and line numbers. Whole-repository search is allowed only after the sample test passes. The guide does not write a rule-file path or CLI flags; do not invent the missing pieces.
Limits
The main path only documents:
npx skills add ast-grep/agent-skill
This machine needs ast-grep already installed. Triggering must name it explicitly, for example "Use ast-grep to find..."; do not expect it to auto-select in every situation.
Capability is evidenced only for structural search and the chain "example → rule → test → whole repository → path and line number". It is written as a skill in the Claude Code plugin marketplace, but on the first try do not switch to marketplace click steps that never appear.
The guide does not document ast-grep install commands, billing, language scope, or destination directory. The first pass is read-only lookup only; do not treat it as a refactoring entry point. Keep undocumented items unknown; do not invent operations.