Mass rename/replace across codebase. Use when user asks to rename functions, replace patterns, or refactor code across files. Better than grep for code changes.
Performs syntax-aware code search and replacement across codebases using AST patterns.
/plugin marketplace add settlemint/agent-marketplace/plugin install devtools@settlemintThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/bash-patterns.mdreferences/exploration-guide.mdreferences/rule-schema.mdreferences/terraform-patterns.mdreferences/transformations.mdreferences/typescript-patterns.mdreferences/yaml-patterns.mdtemplates/rule.yml.mdtemplates/sgconfig.yml.md<quick_start>
# SEARCH - Find patterns
sg run -p "console.log($$$)" -l typescript # Find all console.log calls
sg run -p "async function $FUNC($$$)" -l typescript # Find async functions
# EXPLORE - Understand code (read-only)
sg run -p "use$HOOK($$$)" -l tsx --debug-query # See AST structure
sg run -p "import { $$$IMPORTS } from '$MOD'" -l ts --json # JSON output
# REPLACE - Refactor code
sg run -p "console.log($MSG)" -r "logger.info($MSG)" -l ts --debug-query # Preview
sg run -p "console.log($MSG)" -r "logger.info($MSG)" -l ts # Apply
# LINT - Use YAML rules
sg scan -c sgconfig.yml # Run all rules
sg scan -r rules/no-console.yml # Single rule
</quick_start>
<pattern_syntax>
| Syntax | Meaning | Example |
|---|---|---|
$NAME | Single AST node | $FUNC($ARG) |
$$$ | Zero or more nodes | function($$$ARGS) |
$$$NAME | Named multiple nodes | import { $$$IMPORTS } from |
$_ | Anonymous (no capture) | $_.map($$$) |
$$VAR | Unnamed node capture | Tree-sitter specific |
Rules: $ + UPPERCASE + optional digits. Valid: $A, $FUNC1, $_. Invalid: $func, $123.
</pattern_syntax>
<exploration>Explore codebases with ast-grep (read-only operations):
# Understand AST structure
sg run -p "your code pattern" --debug-query -l typescript
# Find all usages across codebase
sg run -p "useQuery($$$)" -l tsx --heading # Group by file
sg run -p "fetch($URL)" -l typescript -A 3 -B 3 # With context
# JSON output for analysis
sg run -p "$_.$METHOD($$$)" -l typescript --json | jq '.[] | .file'
# Audit patterns
sg run -p "eval($$$)" -l typescript # Security audit
sg run -p "any" -l typescript # Find type annotations
Interactive playground: https://ast-grep.github.io/playground.html
</exploration><cli_commands>
| Command | Purpose | Key Flags |
|---|---|---|
sg run | Search/replace | -p pattern, -r rewrite, -l lang, -i interactive |
sg scan | Lint with rules | -c config, -r rule, --json, --format github |
sg test | Test YAML rules | -c config, -U update snapshots |
sg new | Scaffold project/rules | project, rule, test |
Common flags: --debug-query (preview), --json (output), -A/-B/-C (context), --heading (group)
</cli_commands>
<routing>Load reference files based on context:
| Working On | Load Reference | Command |
|---|---|---|
| Exploring codebase | exploration-guide.md | Understanding patterns, auditing |
| TypeScript/TSX | typescript-patterns.md | Functions, imports, React, types |
| Bash/shell | bash-patterns.md | Variables, conditionals, loops |
| Terraform (.tf) | terraform-patterns.md | Resources, variables, modules |
| Helm/YAML | yaml-patterns.md | Values, K8s resources |
| Writing YAML rules | rule-schema.md | Full rule syntax |
| Transformations | transformations.md | substring, replace, convert |
Note: Markdown is NOT supported (use ripgrep instead).
</routing><common_patterns>
TypeScript (most common):
# Functions
sg -p "async function $FUNC($$$)" -l typescript
sg -p "const $NAME = ($$$) => $BODY" -l typescript
sg -p "const $NAME = async ($$$) => $BODY" -l typescript
# Imports
sg -p 'import { $$$IMPORTS } from "$MODULE"' -l typescript
sg -p 'import $DEFAULT from "$MODULE"' -l typescript
# React
sg -p "use$HOOK($$$)" -l tsx
sg -p "<$COMPONENT $$$PROPS />" -l tsx
sg -p "useState($INITIAL)" -l tsx
# Types
sg -p "interface $NAME { $$$BODY }" -l typescript
sg -p "type $NAME = $TYPE" -l typescript
# Common refactors
sg -p "console.log($$$)" -r "" -l typescript # Remove console.log
sg -p '$A && $A()' -r '$A?.()' -l typescript # Optional chaining
</common_patterns>
<vs_grep>
| Use ast-grep (sg) | Use ripgrep (rg) |
|---|---|
| Syntax-aware matching | Raw text/regex search |
| Ignores strings/comments | All text matches |
| Precise refactoring | Fast file search |
| Pattern-based replacement | Simple find/replace |
| TypeScript, HCL, Bash, YAML | Markdown, config files |
Rule of thumb: Use sg for code structure, rg for text content.
</vs_grep>
<lsp_complement> Use LSP to verify refactoring scope before applying ast-grep changes:
ast-grep excels at pattern-based transformations, but LSP provides semantic verification:
lspFindReferences(lineHint) - Understand full impact before pattern replacementlspCallHierarchy(lineHint) - Trace call chains that will be affectedWorkflow:
lspFindReferences → verify scope is as expectedCRITICAL: Always search first to get lineHint (1-indexed line number). Never call LSP tools without a lineHint from search results.
When to use:
Load LSP skill for detailed patterns: Skill({ skill: "devtools:typescript-lsp" })
</lsp_complement>
Supported (31 languages): Bash, C, C++, C#, CSS, Elixir, Go, Haskell, HCL, HTML, Java, JavaScript, JSON, Kotlin, Lua, Nix, PHP, Python, Ruby, Rust, Scala, Solidity, Swift, TypeScript, TSX, YAML
Language flags: -l typescript, -l tsx, -l hcl, -l bash, -l yaml
Not supported: Markdown (use ripgrep)
</languages> <constraints> **Banned:** - Using grep for code structure changes (use ast-grep) - Applying changes without `--debug-query` preview first - Wrong language flag (tsx vs typescript matters) - Patterns that match strings/comments when code is intendedRequired:
--debug-query before refactors--json output for programmatic workflows
</constraints><anti_patterns>
$_ when you need to capture the value for replacement$$$ for variadic matches (function arguments)-l typescript and -l tsx
</anti_patterns>mcp__plugin_devtools_octocode__githubSearchCode({
queries: [
{
mainResearchGoal: "Find ast-grep rule patterns",
researchGoal: "Search for YAML rules and pattern syntax",
reasoning: "Need real-world examples of ast-grep usage",
keywordsToSearch: ["sgconfig", "ast-grep", "rule"],
extension: "yml",
limit: 10,
},
],
});
Common searches:
keywordsToSearch: ["rule:", "pattern:", "fix:"]keywordsToSearch: ["sg run", "-l typescript", "console.log"]keywordsToSearch: ["use$HOOK", "-l tsx", "useState"]
</research><related_skills>
Code search: Load via Skill({ skill: "devtools:troubleshooting" }) when:
React patterns: Load via Skill({ skill: "devtools:react" }) when:
Testing: Load via Skill({ skill: "devtools:vitest" }) when:
<success_criteria>
--debug-query)tsx for JSX, typescript for pure TS)--json for programmatic analysis
</success_criteria>Timelessness: AST-based search and replace is fundamentally more reliable than regex for code transformations. </evolution>
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.