atman-33/serena-skills

Serena Skills

Standalone Serena MCP tools for code intelligence without requiring MCP server.

Quick Start

When running from project root, use full path to scripts:

1. (Optional) Register project:

   python .claude/skills/serena-skills/scripts/project-config/activate_project.py --project-path .
   

2. Get structure:

   # get_symbols_overview.py: Use --file parameter (not --path)
   python .claude/skills/serena-skills/scripts/symbol-search/get_symbols_overview.py --project-root . --file src/main.ts
   

3. Locate target:

   # find_symbol.py: Use --pattern parameter (not --symbol)
   python .claude/skills/serena-skills/scripts/symbol-search/find_symbol.py --project-root . --pattern "MyClass"
   

4. Edit:

   python .claude/skills/serena-skills/scripts/code-editor/replace_content.py --project-root . --file src/main.ts --old-string "old" --new-string "new"
   

All scripts support --project-root parameter (use . for current directory when running from project root).

Tool Categories

Maps Serena MCP tools to standalone scripts organized by category.

When running from project root, use path: .claude/skills/serena-skills/scripts/<category>/<script>.py

Symbol Search (.claude/skills/serena-skills/scripts/symbol-search/)

LSP-based code analysis - maps to Serena MCP symbol tools:

• get_symbols_overview.py (--file) - File structure overview (classes, functions, methods)
• find_symbol.py (--pattern) - Search by name path pattern (Class/method, /absolute/path)
• find_referencing_symbols.py (--symbol-name) - Find all usages of a symbol
• insert_after_symbol.py / insert_before_symbol.py (--symbol-path) - Insert code around symbols
• rename_symbol.py (--old-name, --new-name) - Safe refactoring with automatic reference updates

Memory Management (.claude/skills/serena-skills/scripts/memory-manager/)

Persistent project knowledge - maps to Serena MCP memory tools:

• write_memory.py (--name, --content) / read_memory.py (--name) - Store/retrieve project knowledge
• list_memories.py / delete_memory.py (--name) / edit_memory.py (--name, --content) - Manage memories

Storage: .tmp/.serena-skills/memories/

File Operations (.claude/skills/serena-skills/scripts/file-ops/)

File system operations - maps to Serena MCP file tools:

• read_file.py (--file) - Read file contents or line ranges
• list_dir.py (--path) - List directories (with recursion support)
• find_file.py (--pattern) - Find files by name pattern (wildcards)
• search_for_pattern.py (--pattern) - Regex search with context (grep-like)

Code Editor (.claude/skills/serena-skills/scripts/code-editor/)

Code modification - maps to Serena MCP editing tools:

• replace_symbol_body.py (--symbol-path, --new-body) - Symbol-level replacement (LSP-aware)
• replace_content.py (--file, --old-string, --new-string) - Text-based find/replace (literal or regex)
• create_text_file.py (--file, --content) - Create new file
• delete_lines.py / replace_lines.py / insert_at_line.py (--file, --line) - Line-based edits

Project Config (.claude/skills/serena-skills/scripts/project-config/)

Project setup and configuration - maps to Serena MCP config tools:

• activate_project.py (--project-path) - Register and configure project (creates .tmp/.serena-skills/)
• list_projects.py - Show all registered projects
• get_config.py (--project-root) - Display current configuration
• get_project_config.py / update_project_config.py (--project-root) - Manage project.yml
• remove_project.py (--project-root) - Unregister project

Workflow Assistant (.claude/skills/serena-skills/scripts/workflow-assistant/)

Workflow helpers - maps to Serena MCP workflow tools:

• check_onboarding.py / create_onboarding.py / get_onboarding.py / update_onboarding.py - Onboarding docs
• think_collected_info.py - Reflect on information completeness
• think_task_adherence.py - Verify task alignment before code changes
• think_are_done.py - Check completion before finalizing

Shell Executor (.claude/skills/serena-skills/scripts/shell-executor/)

Command execution - maps to Serena MCP command tool:

• execute_shell_command.py (--command) - Safe shell execution with timeout protection

Usage Patterns

Note: When running from project root, prefix all script paths with .claude/skills/serena-skills/scripts/

Understanding New Codebase

1. python .claude/skills/serena-skills/scripts/file-ops/list_dir.py --project-root . --path . --recursive - Get structure
2. python .claude/skills/serena-skills/scripts/symbol-search/get_symbols_overview.py --project-root . --file src/main.ts - Overview key files
3. python .claude/skills/serena-skills/scripts/symbol-search/find_symbol.py --project-root . --pattern "Class" --include-body - Explore implementations
4. python .claude/skills/serena-skills/scripts/memory-manager/write_memory.py --project-root . --name "findings" --content "..." - Document findings

Making Code Changes

1. python .claude/skills/serena-skills/scripts/symbol-search/find_symbol.py --project-root . --pattern "target" - Locate target
2. python .claude/skills/serena-skills/scripts/symbol-search/find_referencing_symbols.py --project-root . --symbol "target" - Check impact
3. python .claude/skills/serena-skills/scripts/code-editor/replace_content.py --project-root . --file src/file.ts --old-string "old" --new-string "new" - Edit
4. python .claude/skills/serena-skills/scripts/shell-executor/execute_shell_command.py --project-root . --command "npm test" - Run tests

Refactoring

1. python .claude/skills/serena-skills/scripts/symbol-search/find_symbol.py --project-root . --pattern "target" - Understand structure
2. python .claude/skills/serena-skills/scripts/symbol-search/find_referencing_symbols.py --project-root . --symbol "target" - Map dependencies
3. python .claude/skills/serena-skills/scripts/symbol-search/rename_symbol.py --project-root . --old-name "OldName" --new-name "NewName" - Safe rename across codebase
4. python .claude/skills/serena-skills/scripts/code-editor/replace_symbol_body.py --project-root . --symbol "target" --new-body "..." - Modify implementations

When to Use What

Understanding code? → symbol-search/get_symbols_overview.py → symbol-search/find_symbol.py

Modifying code? → code-editor/replace_symbol_body.py (symbol-level) or code-editor/replace_content.py (text-level)

Searching? → file-ops/search_for_pattern.py (text) or symbol-search/find_symbol.py (symbols)

Widespread changes? → symbol-search/rename_symbol.py (names) or code-editor/replace_content.py (patterns)

Track findings? → memory-manager/write_memory.py (session) or workflow-assistant/update_onboarding.py (permanent)

All paths relative to .claude/skills/serena-skills/scripts/ when running from project root.

Symbol vs Text Editing

Symbol-level (LSP-aware):

• Entire functions/methods/classes
• Type-aware, reference-aware
• Tools: code-editor/replace_symbol_body.py, symbol-search/insert_*_symbol.py, symbol-search/rename_symbol.py

Text-level (pattern matching):

• Small targeted changes, comments, strings
• Regex support, multi-location edits
• Tools: code-editor/replace_content.py, code-editor/*_lines.py, code-editor/insert_at_line.py

All paths relative to .claude/skills/serena-skills/scripts/ when running from project root.

Technical Notes

Requirements:

• Python 3.8+
• Language servers for LSP tools (e.g., pyright for Python)
• Auto-detects .venv when present

Storage:

• Project data: {project}/.tmp/.serena-skills/
• Memories: {project}/.tmp/.serena-skills/memories/
• Config: {project}/.tmp/.serena-skills/project.yml

Troubleshooting:

• LSP timeout → Language mismatch or large project
  • Cause: Wrong language server (e.g., Pyright for TypeScript)
  • Fix: Specify --language typescript or run activate_project.py --project-path . --language typescript
  • Or: Increase timeout with --lsp-timeout 20 for large projects
• LSP fails → Install language server
• Module not found → Install deps (see SETUP.md)
• No python3 → Use python
• lib import errors → Set PYTHONPATH:
  • Windows PowerShell: $env:PYTHONPATH = ".claude/skills/serena-skills"
  • Linux/macOS/WSL: export PYTHONPATH=.claude/skills/serena-skills
  • Or run: cd .claude/skills/serena-skills && python scripts/...

Setup and Installation

See SETUP.md for complete installation guide, including:

• System requirements
• Installation methods (system-wide or virtual environment)
• Language server setup
• Verification steps
• Usage examples and troubleshooting