Initial commit

skills/ast-grep/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ast-grep
+description: Use ast-grep for structural code search and refactoring when editing code structure with ambiguity in text matching, handling "old_string not unique" problems, or performing formatting-independent pattern matching across function signatures, method calls, and class structures
+---
+
+# ast-grep: Structural Code Search and Editing
+
+Use ast-grep to solve the "old_string not unique" problem by matching code structure instead of exact text. This enables refactoring across formatting variations and structural patterns.
+
+## When to Use ast-grep vs Text Tools
+
+### Use ast-grep when:
+- **Structural code changes** - Refactoring function signatures, method calls, class structures
+- **Formatting-independent matching** - Need to find code regardless of whitespace/line breaks
+- **Pattern variations** - Matching similar structures with different variable names/arguments
+- **"old_string not unique" problem** - Edit tool fails because text appears in multiple contexts
+- **Complex queries** - Finding nested structures, specific AST patterns
+
+### Use text tools (Edit/Grep) when:
+- **Simple, unique string replacement** - The exact text appears once or in consistent format
+- **Non-code files** - Markdown, configs, data files
+- **Comment/documentation edits** - Content that isn't code structure
+- **Very small changes** - Single line, obvious context, no ambiguity
+
+## Key Decision Rule
+
+**If editing code structure and there's any ambiguity in text matching → use ast-grep.**
+
+ast-grep's primary value: **Solves the "old_string not unique" problem by matching structure instead of exact text.**
+
+## Detailed Reference
+
+For comprehensive patterns, syntax, metavariables, common use cases, language-specific tips, and best practices, load [ast-grep guide](./reference/ast-grep-guide.md).
+
+The reference includes:
+- Pattern syntax and metavariables (`$VAR`, `$$$ARGS`, `$$STMT`)
+- Recommended workflow (search, verify, apply, validate)
+- Common use cases with examples (function calls, imports, method renames)
+- Language-specific tips (JavaScript/TypeScript, Python, Go, Rust)
+- Best practices and pitfalls to avoid
+- Integration strategies with Edit tool