/serena

name: serena
description: This skill provides symbol-level code understanding and navigation using Language Server Protocol (LSP). Enables IDE-like capabilities for finding symbols, tracking references, and making precise code edits at the symbol level.
license: MIT

Serena: Symbol-Level Code Understanding

Navigate and manipulate code at the symbol level using IDE-like semantic analysis powered by Language Server Protocol (LSP).

How You Can Access Serena

You may have Serena available in one or both of these ways:

**Option 1: Direct MCP Tools** (if configured by your orchestrator) Check your available tools for:

• `find_symbol`, `find_referencing_symbols` - Symbol lookup
• `rename_symbol`, `replace_symbol_body` - Refactoring
• `insert_after_symbol`, `insert_before_symbol` - Precise insertions
• `onboarding`, `activate_project` - Project understanding
• `write_memory`, `read_memory` - Save context
• And 25+ more LSP-powered tools

If you see these tools, use them directly - they provide full Serena capabilities!

**Option 2: CLI Commands** (always available via execute_command) You can run serena commands using:

execute_command("uvx --from git+https://github.com/oraios/serena serena <command>")

This skill focuses on CLI usage patterns. If you have direct MCP tools, prefer those for better integration.

Purpose

The serena skill provides access to Serena, a coding agent toolkit that transforms text-based LLMs into symbol-aware code agents. Unlike traditional text search (ripgrep) or structural search (ast-grep), Serena understands code semantics through LSP integration.

**Key capabilities:**

1. **Symbol Discovery**: Find classes, functions, variables, and types by name across 30+ languages 2. **Reference Tracking**: Discover all locations where a symbol is referenced or used 3. **Precise Editing**: Insert code at specific symbol locations with surgical precision

Serena operates at the **symbol level** rather than the text or syntax level, providing true IDE-like understanding of code structure, scope, and relationships.

When to Use This Skill

Use the serena skill when you need symbol-level code understanding:

**Code Navigation:**

• Finding where a class, function, or variable is defined
• Discovering all places where a symbol is used (call sites, imports, references)
• Understanding code dependencies and relationships
• Tracing execution flow through function calls

**Code Understanding:**

• Analyzing impact of changes to a function or class
• Understanding inheritance hierarchies and type relationships
• Identifying dead code (symbols never referenced)
• Mapping API usage patterns across a codebase

**Code Refactoring:**

• Renaming symbols while tracking all usage locations
• Adding methods or fields to specific classes
• Inserting error handling after specific function calls
• Modifying all call sites of a deprecated function

**Choose serena over file-search (ripgrep/ast-grep) when:**

• You need to understand symbol semantics (not just text patterns)
• You want to track references across files and modules
• You need precise insertion points based on code structure
• You're working with complex, multi-file codebases

**Still use file-search when:**

• Searching for text patterns, comments, or strings
• Finding todos, security issues, or documentation
• You need faster, simpler pattern matching
• Symbol-level precision isn't required

Language Support

Serena uses LSP servers for semantic analysis. Most common languages are supported out-of-the-box:

• Python (pyright, jedi)
• JavaScript/TypeScript (typescript-language-server)
• Rust (rust-analyzer)
• Go (gopls)
• Java (jdtls)
• C/C++ (clangd)
• C#, Ruby, PHP, Kotlin, Swift, Scala, and 15+ more

The LSP servers provide symbol information for the language you're working with.

Core Operations

1. Finding Symbols (`find_symbol`)

Locate where a symbol is **defined** in your codebase.

**Note:** All examples below use the short form `serena <command>`. The full command is:

uvx --from git+https://github.com/oraios/serena serena <command>

# Find a class definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'UserService' --type class")

# Find a function definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'authenticate' --type function")

# Find a variable definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'API_KEY' --type variable")

**Use cases:**

• Locating the definition of a class before modifying it
• Finding where a function is implemented
• Understanding where constants are defined
• Tracing type definitions in typed languages

**Output format:**

File: src/services/user_service.py
Line: 42
Symbol: UserService (class)
Context: class UserService(BaseService):

2. Finding References (`find_referencing_symbols`)

Discover **all locations** where a symbol is used, imported, or referenced.

# Find all usages of a class
execute_command("serena find_referencing_symbols --name 'UserService'")

# Find all call sites of a function
execute_command("serena find_referencing_symbols --name 'authenticate'")

# Find all reads/writes of a variable
execute_command("serena find_referencing_symbols --name 'API_KEY'")

**Use cases:**

• Impact analysis before refactoring
• Finding all call sites of a function
• Tracking API usage across modules
• Identifying unused symbols (zero references)
• Understanding data flow and dependencies

**Output format:**

Found 12 references to 'authenticate':

1. src/api/routes.py:34
   authenticate(user_credentials)

2. src/middleware/auth.py:18
   from services import authenticate

3. tests/test_auth.py:56
   mock_authenticate = Mock(spec=authenticate)
...

3. Precise Code Insertion (`insert_after_symbol`)

Insert code at specific symbol locations with surgical precis