serena-skills

name	serena-skills
description	Standalone Serena MCP tools for code intelligence - symbol search, file ops, memory, editing, config, workflow helpers, and shell execution without MCP server

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