serena-skills

atman-33's avatarfrom atman-33

Complete Serena MCP toolset as standalone skills. Provides symbol search, code editing, file operations, memory management, and project workflow tools without requiring MCP server. Use for code intelligence, analysis, and modification tasks.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Developer Tools]

When & Why to Use This Skill

Serena Skills is a comprehensive suite of standalone tools designed for advanced code intelligence and manipulation without the need for an MCP server. It empowers developers with LSP-based symbol searching, precise code editing, persistent project memory, and automated workflow assistance. By integrating file operations and shell execution, it provides a robust environment for deep codebase analysis, safe refactoring, and efficient project management directly within the AI agent's workflow.

Use Cases

  • Deep Codebase Exploration: Quickly understand complex projects by generating symbol overviews, mapping class structures, and finding specific symbol definitions using LSP-aware search tools.
  • Precision Code Refactoring: Perform safe, project-wide renames and code replacements that maintain reference integrity, moving beyond simple text-based find-and-replace.
  • Persistent Project Knowledge: Use the built-in memory management system to store and retrieve architectural decisions, findings, and task progress across different AI sessions.
  • Automated Workflow Management: Streamline development cycles with specialized scripts for onboarding documentation, task adherence verification, and safe shell command execution for testing.
nameserena-skills
descriptionStandalone 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
serena-skills – AI Agent Skills | Claude Skills