Initial commit

skills/using-serena-for-exploration/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: using-serena-for-exploration
+description: Use when exploring codebases with Serena MCP tools for architectural understanding and pattern discovery - guides efficient symbolic exploration workflow minimizing token usage through targeted symbol reads, overview tools, and progressive narrowing
+---
+
+# Using Serena for Exploration
+
+Use this skill when exploring codebases with Serena MCP tools for architectural understanding and pattern discovery.
+
+## Core Principles
+
+- Start broad, narrow progressively
+- Use symbolic tools before reading full files
+- Always provide file:line references
+- Minimize token usage through targeted reads
+
+## Workflow
+
+### 1. Initial Discovery
+
+**Use `list_dir` and `find_file`** to understand project structure:
+
+```bash
+# Get repository overview
+list_dir(relative_path=".", recursive=false)
+
+# Find specific file types
+find_file(file_mask="*auth*.py", relative_path="src")
+```
+
+### 2. Symbol Overview
+
+**Use `get_symbols_overview`** before reading full files:
+
+```python
+# Get top-level symbols in a file
+get_symbols_overview(relative_path="src/auth/handler.py")
+```
+
+Returns classes, functions, imports - understand structure without reading bodies.
+
+### 3. Targeted Symbol Reading
+
+**Use `find_symbol`** for specific code:
+
+```python
+# Read a specific class without body
+find_symbol(
+    name_path_pattern="AuthHandler",
+    relative_path="src/auth/handler.py",
+    include_body=false,
+    depth=1  # Include methods list
+)
+
+# Read specific method with body
+find_symbol(
+    name_path_pattern="AuthHandler/login",
+    relative_path="src/auth/handler.py",
+    include_body=true
+)
+```
+
+**Name path patterns:**
+- Simple name: `"login"` - matches any symbol named "login"
+- Relative path: `"AuthHandler/login"` - matches method in class
+- Absolute path: `"/AuthHandler/login"` - exact match within file
+- With index: `"AuthHandler/login[0]"` - specific overload
+
+### 4. Pattern Searching
+
+**Use `search_for_pattern`** when you don't know symbol names:
+
+```python
+# Find all JWT usage
+search_for_pattern(
+    substring_pattern="jwt\\.encode",
+    relative_path="src",
+    restrict_search_to_code_files=true,
+    context_lines_before=2,
+    context_lines_after=2,
+    output_mode="content"
+)
+```
+
+**Pattern matching:**
+- Uses regex with DOTALL flag (. matches newlines)
+- Non-greedy quantifiers preferred: `.*?` not `.*`
+- Escape special chars: `\\{\\}` for literal braces
+
+### 5. Relationship Discovery
+
+**Use `find_referencing_symbols`** to understand dependencies:
+
+```python
+# Who calls this function?
+find_referencing_symbols(
+    name_path="authenticate_user",
+    relative_path="src/auth/handler.py"
+)
+```
+
+Returns code snippets around references with symbolic info.
+
+## Reporting Format
+
+Always structure findings as:
+
+```markdown
+## Codebase Findings
+
+### Current Architecture
+- **Authentication:** `src/auth/handler.py:45-120`
+  - JWT-based auth with refresh tokens
+  - Session storage in Redis
+
+### Similar Implementations
+- **User management:** `src/users/controller.py:200-250`
+  - Uses similar validation pattern
+  - Can reuse `validate_credentials()` helper
+
+### Integration Points
+- **Middleware:** `src/middleware/auth.py:30`
+  - Hook new auth method here
+  - Follows pattern: check → validate → attach user
+```
+
+## Anti-Patterns
+
+❌ **Don't:** Read entire files before understanding structure
+✅ **Do:** Use `get_symbols_overview` first
+
+❌ **Don't:** Use full file reads for symbol searches
+✅ **Do:** Use `find_symbol` with targeted name paths
+
+❌ **Don't:** Search without context limits
+✅ **Do:** Use `relative_path` to restrict search scope
+
+❌ **Don't:** Return findings without file:line references
+✅ **Do:** Always include exact locations: `file.py:123-145`
+
+## Token Efficiency
+
+- Overview tools use ~500 tokens vs. ~5000 for full file
+- Targeted symbol reads use ~200 tokens per symbol
+- Pattern search with `head_limit=20` caps results
+- Use `depth=0` if you don't need child symbols
+
+## Example Session
+
+```python
+# 1. Find auth-related files
+files = find_file(file_mask="*auth*.py", relative_path="src")
+# → Found: src/auth/handler.py, src/auth/middleware.py
+
+# 2. Get overview of main handler
+overview = get_symbols_overview(relative_path="src/auth/handler.py")
+# → Classes: AuthHandler
+# → Functions: authenticate_user, validate_token
+
+# 3. Read specific method
+method = find_symbol(
+    name_path_pattern="AuthHandler/authenticate_user",
+    relative_path="src/auth/handler.py",
+    include_body=true
+)
+# → Got full implementation of authenticate_user
+
+# 4. Find who calls this
+refs = find_referencing_symbols(
+    name_path="authenticate_user",
+    relative_path="src/auth/handler.py"
+)
+# → Called from: middleware.py:67, api/routes.py:123
+```