Skip to content
Back to search

agent-skill

ast-grep Plugin Marketplace for AI Agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ast-grep--agent-skill/badge.svg)](/listings/ast-grep--agent-skill)

HTML

<a href="/listings/ast-grep--agent-skill"><img src="/api/listings/ast-grep--agent-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Install via skills.sh (Recommended)

npx skills add ast-grep/agent-skill

Option 2: Install via Marketplace

1. **Add the marketplace** to your Claude Code:

/plugin marketplace add ast-grep/agent-skill

2. **Install the ast-grep plugin**:

/plugin install ast-grep

`/plugin install` activates the plugin in the running session, reporting `Installed ast-grep. Plugin is now active.`, so no restart is needed. Run `/plugin` to confirm it is listed.

Option 3: Install Locally for Development

If you're developing or testing locally:

# Clone the repository
git clone https://github.com/ast-grep/agent-skill.git /path/to/local-marketplace

# Add as local marketplace
/plugin marketplace add /path/to/local-marketplace

# Install the plugin
/plugin install ast-grep

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 28 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ast-grep-marketplace",
  3. "owner": {
  4. "name": "Herrington Darkholme"
  5. },
  6. "metadata": {
  7. "description": "A marketplace for Claude Code skills including ast-grep structural code search",
  8. "version": "1.0.0",
  9. "repository": "https://github.com/ast-grep/agent-skill",
  10. "homepage": "https://github.com/ast-grep/agent-skill"
  11. },
  12. "plugins": [
  13. {
  14. "name": "ast-grep",
  15. "source": "./ast-grep",
  16. "description": "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.",
  17. "version": "1.0.0",
  18. "keywords": [
  19. "ast-grep",
  20. "code-search",
  21. "ast",
  22. "structural-search",
  23. "pattern-matching",
  24. "refactoring"
  25. ]
  26. }
  27. ]
  28. }
README.md · README · 282 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ast-grep Plugin Marketplace for AI Agents
  2. A Claude Code plugin marketplace containing the ast-grep skill for powerful structural code search using Abstract Syntax Tree (AST) patterns. Search your codebase based on code structure rather than just text matching.
  3. ## What is This?
  4. This is a **Claude Code plugin marketplace** that provides the **ast-grep plugin**. The plugin includes a skill that teaches Claude how to write and use ast-grep rules to perform advanced code searches. Unlike traditional text-based search (grep, ripgrep), ast-grep understands the structure of your code, allowing you to find patterns like:
  5. - "Find all async functions that don't have error handling"
  6. - "Locate all React components that use a specific hook"
  7. - "Find functions with more than 3 parameters"
  8. - "Search for console.log calls inside class methods"
  9. ## Prerequisites
  10. You need to have ast-grep installed on your system:
  11. ```bash
  12. # macOS
  13. brew install ast-grep
  14. # npm
  15. npm install -g @ast-grep/cli
  16. # cargo
  17. cargo install ast-grep
  18. ```
  19. Verify installation:
  20. ```bash
  21. ast-grep --version
  22. ```
  23. ## Installation
  24. ### Option 1: Install via skills.sh (Recommended)
  25. ```
  26. npx skills add ast-grep/agent-skill
  27. ```
  28. ### Option 2: Install via Marketplace
  29. 1. **Add the marketplace** to your Claude Code:
  30. ```bash
  31. /plugin marketplace add ast-grep/agent-skill
  32. ```
  33. 2. **Install the ast-grep plugin**:
  34. ```bash
  35. /plugin install ast-grep
  36. ```
  37. `/plugin install` activates the plugin in the running session, reporting `Installed ast-grep. Plugin is now active.`, so no restart is needed.
  38. Run `/plugin` to confirm it is listed.
  39. ### Option 3: Install Locally for Development
  40. If you're developing or testing locally:
  41. ```bash
  42. # Clone the repository
  43. git clone https://github.com/ast-grep/agent-skill.git /path/to/local-marketplace
  44. # Add as local marketplace
  45. /plugin marketplace add /path/to/local-marketplace
  46. # Install the plugin
  47. /plugin install ast-grep
  48. ```
  49. ## How to Use
  50. Once installed, ask Claude to search your code using structural patterns.
  51. Installing the skill makes it **discovered**, not **preferred**.
  52. Claude Code loads it and matches its description against your query, but on any given search it is also holding a text-search tool that needs no setup, so it often takes that instead.
  53. Naming ast-grep or structural search ("Use ast-grep to find...") invokes the skill reliably.
  54. To get that preference without repeating it every query, state it once in your `AGENTS.md` or `CLAUDE.md`:
  55. ```markdown
  56. You are operating in an environment where `ast-grep` is installed.
  57. For any code search that requires understanding of syntax or code structure, you should default to using `ast-grep --lang [language] -p '<pattern>'`.
  58. Adjust the `--lang` flag as needed for the specific programming language.
  59. Avoid using text-only search tools unless a plain-text search is explicitly requested.
  60. ```
  61. See [Using ast-grep with AI Tools](https://ast-grep.github.io/advanced/prompting.html) for more on prompting, including feeding the docs to an agent and the MCP server.
  62. ### Example Queries
  63. **Find async functions with await:**
  64. ```
  65. Find all async functions in this project that use await
  66. ```
  67. **Find missing error handling:**
  68. ```
  69. Show me async functions that don't have try-catch blocks
  70. ```
  71. **Find specific function calls:**
  72. ```
  73. Find all places where we call console.log with more than one argument
  74. ```
  75. **Find code in specific contexts:**
  76. ```
  77. Find all setState calls inside useEffect hooks
  78. ```
  79. ### How It Works
  80. When you ask Claude to search for code patterns:
  81. 1. Claude analyzes your query and determines if ast-grep is appropriate
  82. 2. It creates example code that matches your search criteria
  83. 3. It writes an ast-grep rule to match the pattern
  84. 4. It tests the rule against the example code
  85. 5. Once verified, it searches your entire codebase
  86. 6. Results are presented with file paths and line numbers
  87. ## Supported Languages
  88. ast-grep supports many programming languages including:
  89. - JavaScript/TypeScript
  90. - Python
  91. - Rust
  92. - Go
  93. - Java
  94. - C/C++
  95. - Ruby
  96. - PHP
  97. - And many more
  98. ## Key Features
  99. - **Structure-aware search**: Matches code based on AST structure, not just text
  100. - **Metavariables**: Use `$VAR` to match any expression, statement, or identifier
  101. - **Relational queries**: Find code inside specific contexts (e.g., "find X inside Y")
  102. - **Composite logic**: Combine rules with AND, OR, NOT operations
  103. - **Test-driven approach**: Rules are tested before running on your codebase
  104. ## Advanced Usage
  105. ### Direct ast-grep Commands
  106. While Claude will handle most use cases automatically, you can also use ast-grep directly:
  107. ```bash
  108. # Simple pattern search
  109. ast-grep run --pattern 'console.log($ARG)' --lang javascript .
  110. # Complex rule-based search
  111. ast-grep scan --inline-rules "id: my-rule
  112. language: javascript
  113. rule:
  114. kind: function_declaration
  115. has:
  116. pattern: await \$EXPR
  117. stopBy: end" .
  118. ```
  119. ### Debugging
  120. If a search isn't working as expected, ask Claude to:
  121. - Show you the ast-grep rule it created
  122. - Inspect the AST structure of your code
  123. - Test the rule against example code
  124. A zero-match run exits successfully, so "no results" and "wrong pattern" look identical.
  125. Two things help when a pattern is the suspect:
  126. - Load [`llms-full.txt`](https://ast-grep.github.io/llms-full.txt), the whole ast-grep documentation as one file, into the agent's context so it stops guessing at rule syntax.
  127. - Use [`ast-grep-mcp`](https://github.com/ast-grep/ast-grep-mcp) to let the agent dump the AST and test a pattern against a snippet, iterating instead of committing to one guess.
  128. ## Repository Structure
  129. This is a Claude Code plugin marketplace repository with the following structure:
  130. ```
  131. agent-skill/
  132. ├── .claude-plugin/
  133. │ └── marketplace.json # Marketplace manifest
  134. ├── ast-grep/ # ast-grep plugin
  135. │ ├── .claude-plugin/
  136. │ │ └── plugin.json # Plugin manifest
  137. │ └── skills/
  138. │ ├── ast-grep/
  139. │ │ ├── SKILL.md # Skill instructions for Claude
  140. │ │ └── references/
  141. │ │ └── rule_reference.md # ast-grep rule documentation
  142. │ └── outline/
  143. │ └── SKILL.md # Structural codebase map skill
  144. └── README.md # This file
  145. ```
  146. ### Key Files
  147. - **`.claude-plugin/marketplace.json`**: Marketplace manifest defining available plugins
  148. - **`ast-grep/.claude-plugin/plugin.json`**: Plugin manifest for the ast-grep plugin
  149. - **`ast-grep/skills/ast-grep/SKILL.md`**: Main skill instructions that Claude uses
  150. - **`ast-grep/skills/ast-grep/references/`**: Supporting documentation and reference materials
  151. - **`ast-grep/skills/outline/SKILL.md`**: Cheap structural map of a codebase, for exploring before reading full source
  152. ## Tips for Best Results
  153. 1. **Be specific**: The more details you provide, the better the search results
  154. 2. **Provide examples**: If possible, show Claude an example of what you want to find
  155. 3. **Iterate**: Start with a broad search and narrow it down
  156. 4. **Ask for explanations**: Ask Claude to explain the ast-grep rule it creates
  157. ## Examples of What You Can Search For
  158. ### Code Quality
  159. - Functions without return statements
  160. - Functions with too many parameters
  161. - Unused variables
  162. - Missing null checks
  163. ### Patterns
  164. - React hooks usage patterns
  165. - API call patterns
  166. - Database query patterns
  167. - Error handling patterns
  168. ### Refactoring
  169. - Find all uses of deprecated functions
  170. - Locate code that needs migration
  171. - Find inconsistent patterns across codebase
  172. ### Security
  173. - Potential SQL injection points
  174. - Unsafe eval usage
  175. - Missing input validation
  176. ## Troubleshooting
  177. **Claude isn't using the skill:**
  178. - Make sure ast-grep is installed (`ast-grep --version`)
  179. - Try being more explicit: "Use ast-grep to search for..."
  180. **No results found:**
  181. - Try a simpler query first
  182. - Ask Claude to show you the rule and test it
  183. - Provide an example of code you want to match
  184. **Unexpected results:**
  185. - Refine your query with more details
  186. - Ask Claude to exclude certain patterns
  187. - Request to see the AST structure of your code
  188. ## Contributing
  189. To improve this skill:
  190. 1. Edit `SKILL.md` to update Claude's instructions
  191. 2. Add examples to `references/` directory
  192. 3. Test with various code patterns
  193. ## Resources
  194. - [ast-grep Official Documentation](https://ast-grep.github.io/)
  195. - [ast-grep Playground](https://ast-grep.github.io/playground.html) - Test patterns online
  196. - [ast-grep GitHub](https://github.com/ast-grep/ast-grep)
  197. ## License
  198. This skill follows ast-grep's MIT license for any included documentation or examples.
  199. ## Support
  200. For issues with:
  201. - **This skill**: Open an issue in this repository
  202. - **ast-grep itself**: Visit [ast-grep GitHub](https://github.com/ast-grep/ast-grep)
  203. - **Claude Code**: Check [Claude Code documentation](https://code.claude.com/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.