serena-usage

name	Serena Usage
description	This skill should be used when the user asks to "use serena", "semantic search", "symbol analysis", "find references", "code navigation", or needs Serena MCP guidance. Provides Serena tool usage patterns and orchestration integration.
version	3.2.0

Provide patterns for effective use of Serena MCP tools for semantic code operations, memory management, and orchestration workflow integration. Activate a Serena project for memory and symbol access Project name to activate (required) First step in any session to enable Serena functionality Verify if project onboarding has been completed After activate_project, ensure project is fully onboarded Perform initial project onboarding When check_onboarding_performed returns false Get high-level view of symbols in a file Path to file (required) Descendant depth, 0 for top-level only First step when exploring a new file; prefer depth=0 initially Find symbols by name path pattern Symbol name or path (e.g., "MyClass/myMethod") Restrict to file or directory Include source code (default false) Include descendants Match partial names (useful for uncertain names) Locate specific functions, classes, or methods Find all references to a symbol Symbol to find references for File containing the symbol Dependency analysis, impact assessment before refactoring Replace entire symbol definition Symbol to replace File containing symbol New symbol body Refactoring entire functions or classes Insert content before a symbol Symbol to insert before File containing symbol Content to insert Add imports, decorators, comments before a symbol Insert content after a symbol Symbol to insert after File containing symbol Content to insert Add new functions, classes after a symbol Rename symbol across codebase with automatic reference updates Symbol to rename File containing symbol New symbol name Consistent renaming with reference updates across all files List all available memory files Check existing patterns before implementation Read content of a memory file Name of memory file to read Load project patterns and conventions Write information to a memory file (creates or overwrites) Name of memory file to write Content to write Record new patterns and conventions for future sessions Replace content in a memory file using regex or literal matching Name of memory file to edit Pattern to search for Replacement string Either "literal" or "regex" Update specific parts of memory files without full rewrite Rename a memory file Current name of the memory file New name for the memory file Rename memories for better organization or archival Delete a memory file Name of memory file to delete Remove obsolete or incorrect patterns (requires user permission) Get current Serena configuration for the active project Verify project settings and available language servers Read the Serena Instructions Manual Must be called at session start before any other Serena tool to load the manual Find the declaration of a symbol using a regex with one capture group File containing the symbol reference (required) Regex with exactly one capture group matching the symbol; surround the group with enough context to make the match unambiguous (required) Optional: restrict search to body of a specific containing symbol Include the declaration's source code (default false) Include hover-like info (default false) Jump to declaration when you have a call site but not the definition location; example: to find the declaration of `process` in a call `obj.process(x)`, pass regex `"obj\.(process)\("` Find all implementations of a symbol (e.g., interface or abstract class) Symbol to find implementations for (required) File containing the symbol — must be a file, not a directory (required) Include hover-like info about implementing symbols (default false) Discover all concrete implementations of an interface or abstract type Get LSP diagnostics (errors, warnings, hints) for a file File to inspect (required) Minimum severity to include: 1=Error, 2=Warning, 3=Information, 4=Hint (default 4) First 0-based line to include (default 0) Last 0-based line to include, -1 means end of file (default -1) Verify a file is error-free after editing; use min_severity=2 to filter out hint noise Replace content in a file using regex or literal matching — the primary tool for sub-symbol edits File to edit (required) String or regex pattern to search for (required) Replacement string; regex mode supports backreferences as $!1, $!2, ... (required) Either "literal" or "regex" (required) Replace all matches if true; error if multiple found when false (default false) Sub-symbol edits where replace_symbol_body would be too broad; prefer regex mode with wildcards (e.g., "beginning.*?end") to avoid specifying full content Delete a symbol only if it has no references; returns reference list if unsafe Symbol to delete (required) File containing the symbol (required) Safely remove dead code without risk of dangling references; inspect returned references before proceeding if deletion is blocked Persistent storage for project patterns, conventions, and architectural decisions that survive across sessions list_memories # Check existing patterns read_memory "nix-conventions" # Load Nix patterns write_memory "api-patterns" "REST API conventions..." # Record new pattern edit_memory "api-patterns" "old text" "new text" mode="literal" # Update memory rename_memory "old-name" "new-name" # Rename for organization Consistent naming conventions for memory files. Names may include "/" to organize into subtopics (e.g., "codex/slash-command-mapping"); list_memories enumerates nested paths transparently. convention-{topic} # Forward-looking project conventions (e.g., convention-nix-module-structure) decision-{topic} # Architectural decision records (e.g., decision-use-home-manager) review-{topic}-YYYY-MM # Past investigation findings (e.g., review-nixvim-2026-05) {feature}-patterns # Feature-specific reusable patterns {domain}-patterns # Domain-specific patterns {project}-conventions # (legacy) Project-wide conventions global/{topic} # Shared across all projects, not just the active one — use only when the # user explicitly instructs a memory to be project-independent (e.g., "global/nix/style-guide") Path to symbol within a file using slash-separated hierarchy (e.g., MyClass/myMethod) find_symbol "MyClass/myMethod" # Find specific method find_symbol "get*" substring_matching=true # Find all getter methods replace_content is the primary tool for sub-symbol edits — changes within a function body, a few lines inside a class, etc. Prefer regex mode with wildcards to avoid transcribing large sections of code. Preferred: regex with wildcard to target a region replace_content relative_path="src/main.ts" needle="function foo\(.*?\) \{.*?return old" repl="function foo() {\n return new" mode="regex"

  <note>Literal match for exact short strings</note>
  replace_content relative_path="config.nix" needle="oldValue = true" repl="oldValue = false" mode="literal"
</example>

Serena resolves code intelligence through language servers (LSP). Each supported language is registered in a Language enum with a filename matcher (its file extensions) and mapped to a language-server class through a factory. A project has a set of active languages; symbol tools only work for files whose language is active and backed by a working LSP. This shapes both how the tool is extended and why it sometimes cannot help. Extending Serena to a new language is an LSP-integration task, not a parser-writing task. The decisive choices are which existing language server to wrap and how it is installed and launched. Wrap an existing language server rather than writing a parser. Prefer the single-core-dependency provider when the server is one executable or archive; use the multi-dependency base provider only when setup is genuinely complex. Register the language: add it to the Language enum with a filename matcher for its extensions, and add a factory branch that constructs the server. Provide a minimal test repository that exercises symbols, within-file references, and cross-file references. Write tests that assert the actual expected symbol names and reference locations were found. Asserting only that a non-empty list or a non-null result came back is insufficient and is the most common reason such contributions are rejected. Mandatory LSP capabilities for symbol tools are documentSymbol, definition, and references. A server missing any of these cannot back find_symbol or find_referencing_symbols and should be deferred, or offered only as experimental (completion/hover) support. Installation footprint (extra runtimes or package managers the server needs) determines adoption cost and CI feasibility. Initialize Serena at session start Step 1: Read Serena manual initial_instructions

  <step order="2">
    <action>Step 2: Activate project</action>
  </step>
  activate_project project="project-name"

  <step order="3">
    <action>Step 3: Verify onboarding</action>
  </step>
  check_onboarding_performed

  <step order="4">
    <action>Step 4: If not onboarded, run onboarding</action>
  </step>
  onboarding (if needed)

  <step order="5">
    <action>Step 5: Check available memories</action>
  </step>
  list_memories
</example>

Systematically explore file structure from high-level to detailed Step 1: Get top-level overview get_symbols_overview relative_path="src/main.ts" depth=0

  <step order="2">
    <action>Step 2: Explore class members</action>
  </step>
  get_symbols_overview relative_path="src/main.ts" depth=1

  <step order="3">
    <action>Step 3: Get specific implementation</action>
  </step>
  find_symbol name_path_pattern="MyClass/myMethod" include_body=true
</example>

Trace symbol dependencies and callers Step 1: Locate the symbol find_symbol name_path_pattern="processData" relative_path="src/processor.ts"

  <step order="2">
    <action>Step 2: Find all callers</action>
  </step>
  find_referencing_symbols name_path="processData" relative_path="src/processor.ts"

  <step order="3">
    <action>Step 3: Recursively trace for full dependency graph</action>
  </step>
  <note>Repeat steps 1-2 for each caller to build complete dependency tree</note>
</example>

Refactor with full impact analysis Step 1: Understand current implementation find_symbol name_path_pattern="MyClass/oldMethod" include_body=true

  <step order="2">
    <action>Step 2: Identify all usages</action>
  </step>
  find_referencing_symbols name_path="MyClass/oldMethod" relative_path="src/myclass.ts"

  <step order="3">
    <action>Step 3: Perform the change</action>
  </step>
  replace_symbol_body name_path="MyClass/oldMethod" relative_path="src/myclass.ts" body="..."

  <step order="4">
    <action>Step 4: Update references if interface changed</action>
  </step>
  <note>If method signature changed, update all calling sites identified in step 2</note>
</example>

Use replace_content for sub-symbol edits where replace_symbol_body would replace too much Step 1: Locate the region to change with find_symbol (include_body=true) find_symbol name_path_pattern="MyClass/myMethod" include_body=true

  <step order="2">
    <action>Step 2: Construct a regex that uniquely targets the lines to replace</action>
  </step>
  <note>Use wildcards to avoid transcribing large sections; DOTALL and MULTILINE are enabled</note>

  <step order="3">
    <action>Step 3: Apply the replacement</action>
  </step>
  replace_content relative_path="src/main.ts" needle="oldPattern.*?boundary" repl="newContent" mode="regex"

  <step order="4">
    <action>Step 4: Verify with diagnostics</action>
  </step>
  get_diagnostics_for_file relative_path="src/main.ts" min_severity=2
</example>

Use memories to maintain consistency across tasks Before implementation list_memories # Check what patterns exist read_memory "typescript-patterns" # Load relevant patterns

  <note>During implementation</note>
  <note>Follow the patterns loaded from memory</note>

  <note>After implementation</note>
  write_memory "api-client-pattern" "HTTP client pattern using fetch with retry logic..."
</example>

When to automatically create or update memories After discovering significant architectural pattern After resolving complex bug with reusable debugging insights After completing feature with reusable implementation pattern When user explicitly mentions a convention or preference After successful refactoring with transferable approach One-off fixes with no broader applicability User-specific temporary preferences Workarounds that should be replaced later Information already documented elsewhere Good: After discovering project uses specific error handling pattern write_memory "error-handling-pattern" "# Error Handling Convention\n\nThis project uses Result type pattern with custom Error enum..."

  <note>Skip: After fixing typo in variable name</note>
  <note>No memory needed - not a reusable pattern</note>
</example>

Which memories to prioritize based on task type 1. {domain}-patterns (e.g., authentication-patterns) 2. architecture-* (architectural decisions) 3. {project}-conventions 1. {feature}-patterns (e.g., api-patterns) 2. {language}-conventions (e.g., typescript-conventions) 3. testing-patterns 1. {project}-conventions 2. code-quality-* patterns 3. architecture-* decisions 1. architecture-* decisions 2. {component}-patterns 3. testing-patterns Standard YAML frontmatter for new Serena memory files, enabling structured filtering and lifecycle management --- domain: <nixvim | home-manager | ai-prompts | nix | general> status: active created: YYYY-MM last-verified: YYYY-MM --- Primary area this memory applies to (nixvim, home-manager, ai-prompts, nix, general) active = current and verified; archived = superseded; draft = unverified hypothesis Year-month the memory was first written (e.g., 2026-05) Year-month the content was last confirmed accurate; set equal to created on initial write Apply to all new memories created via write_memory going forward Do NOT migrate existing memories retroactively — apply only to new entries When editing an existing memory that lacks frontmatter, add it at that time On write_memory: set last-verified = created On edit_memory: update last-verified to current YYYY-MM; leave created unchanged Memory versioning, archival, and consolidation patterns. Freshness is maintained by two complementary mechanisms: memory_staleness_verification runs lazily during normal task execution against only the memories that task happened to read, while the /remember command performs a full periodic sweep across the entire memory index. Use date suffix for major updates: {name}-YYYY-MM claude-code-architecture-2026-01 For minor updates, use edit_memory instead of creating new version When pattern is superseded by new approach Rename with -archived suffix using rename_memory OR delete if no historical value rename_memory "old-pattern" "old-pattern-archived" When multiple small memories cover related topics Merge into single comprehensive memory Instead of: api-auth-pattern, api-error-pattern, api-retry-pattern Create: api-patterns with all three sections Lightweight, opportunistic freshness check applied only to memories actually read during a task — the lazy complement to the full sweep performed by the standalone /remember command. Piggybacks on read_memory calls already mandated by SERENA-B002, so it adds no extra memory reads of its own. A memory loaded via read_memory during this task was relied upon (its content informed a decision, an implementation choice, or an investigation finding) Frontmatter last-verified field (see memory_content_format) — stale if more than 3 months old If frontmatter is absent, treat the memory as a stale candidate on this basis alone and add frontmatter when editing (see memory_content_format rules) edit_memory to bump last-verified to the current YYYY-MM; add frontmatter first if it was missing edit_memory to correct the stale section and bump last-verified rename_memory with an "-archived" suffix; note the reason in output Only memories the task already read for its own purposes Proactively reading additional memories solely to check their freshness — that full-index sweep belongs to the /remember command, not to task execution During implementation, read_memory "nix-conventions" returns content with last-verified: 2026-02 (5 months old, current date 2026-07) Task confirms the described pattern still matches the codebase edit_memory "nix-conventions" needle="last-verified: 2026-02" repl="last-verified: 2026-07" mode="literal" In a multi-language repository, language detection may fix the project's active language on the dominant language. Symbol tools then fail for files of a secondary language — typically an error that reports the active languages and refuses to extract symbols for the target file. Treat this as an ongoing constraint of that repository, not a transient glitch to retry against. get_symbols_overview or find_symbol errors with a message naming the active languages and an inability to extract symbols for the target file get_current_config shows the target file's language is not among the active languages Locate definitions and references with Grep (rg) using symbol-name patterns, searching across both source and tests Edit with text-based tools (replace_content in literal or regex mode, or the standard Edit tool) rather than replace_symbol_body or insert_after_symbol Verify with the language's own build or load step, since get_diagnostics_for_file is also unavailable for the inactive language Confirm the constraint once with get_current_config, then commit to the text-based path; do not repeatedly retry symbol tools that cannot work for an inactive language.

<decision_tree name="serena_code_operation"> What type of code operation is needed? Use get_symbols_overview with depth=0, then depth=1 Use find_symbol with name_path_pattern Use find_symbol with include_body=true Use find_referencing_symbols Use replace_symbol_body Use insert_after_symbol Use insert_before_symbol Use rename_symbol Use find_declaration with a regex capturing the symbol name Use find_implementations Use get_diagnostics_for_file with min_severity=2 Use replace_content with mode="regex" and wildcards Use safe_delete_symbol; inspect returned references if blocked Use Glob for file discovery, Grep for content search; follow up navigation with Serena tools </decision_tree>

<decision_tree name="tool_selection"> What type of operation is needed? Use find_symbol with name_path_pattern Use get_symbols_overview with appropriate depth Use find_referencing_symbols Use replace_symbol_body Use rename_symbol for consistent updates Use insert_before_symbol or insert_after_symbol Use list_memories then read_memory Use write_memory Use edit_memory Use find_declaration with regex Use find_implementations Use get_diagnostics_for_file Use replace_content with regex mode Use safe_delete_symbol Use Glob (find) for files, Grep for content </decision_tree>

<decision_tree name="serena_first_tool_selection"> Tool selection hierarchy: Serena for code intelligence, standard tools for filesystem navigation What type of operation is needed? Use Glob (find with name pattern) Serena no longer provides filesystem navigation tools; Glob is the correct tool for file discovery Use Grep for discovery Use Serena find_symbol or find_referencing_symbols for navigation after identifying location Use Bash ls Use Serena get_symbols_overview (depth=0 first, then depth=1) Use Grep for pattern discovery first, then Read for full context Use Serena find_symbol with name_path_pattern Use find_symbol with substring_matching=true Use Grep Use Serena find_declaration with regex capturing the symbol Use Serena find_implementations Use Serena get_symbols_overview then find_symbol with include_body=true Use Read Use Serena find_referencing_symbols Use Grep with symbol name pattern Use Serena replace_symbol_body Use Serena replace_content with mode="regex" and wildcards Use Serena get_diagnostics_for_file with min_severity=2 Use Serena safe_delete_symbol; inspect returned references if deletion is blocked <unavailable_conditions> Serena project not activated (call initial_instructions then activate_project first) File type not supported by LSP (use Grep or Read) Target file's language is not among the project's active languages — multi-language detection fixed on the dominant language; use Grep plus text edits (see symbol_tools_unavailable_fallback) Tool explicitly fails with error </unavailable_conditions> </decision_tree>

<decision_tree name="language_specific_symbol_operations"> Language-specific guidance for symbol operations Strongly prefer symbol operations (find_symbol, get_symbols_overview) LSP provides accurate symbol resolution Use symbol operations with substring_matching=true Dynamic nature may require broader matching Use Grep for pattern discovery, then Read for full context when structure is complex Use Grep or Read Symbol operations less useful for prose </decision_tree>

Session start Call initial_instructions to read the Serena manual, then activate project with activate_project and check_onboarding_performed Project activation recorded in output Before any implementation Check Serena memories with list_memories Memory check recorded in output After significant pattern discovery or successful implementation Create or update memory with write_memory or edit_memory Memory operation recorded in output for reusable patterns See memory_auto_creation_triggers pattern for when to create When examining code structure or navigating codebase Use get_symbols_overview or find_symbol before Read for code files Symbol operations attempted before full file read Non-code files (YAML, JSON, MD) may use Read directly When saving findings to an existing memory topic First call list_memories to check if a memory for this topic exists; if it exists, use edit_memory to append or update sections; only use write_memory for genuinely new memory topics edit_memory used for existing topics; write_memory only for new ones After relying on the content of a memory that was read via read_memory during this task Follow memory_staleness_verification: check last-verified against a 3-month threshold; bump, correct, or archive as appropriate Staleness check outcome noted in output (verified / updated / archived / already fresh) Always Reading entire files when symbol operations suffice Use get_symbols_overview and find_symbol instead Always Deleting memories without explicit user request Use edit_memory instead or ask user permission When reading code files Using Read for code file discovery instead of Serena symbol tools Use get_symbols_overview and find_symbol for code exploration; Read is forbidden for discovery of code files File/directory navigation (ls, find, grep) uses standard tools; Serena owns code intelligence When exploring code files Using Read without first attempting get_symbols_overview or find_symbol Use symbol operations first; fall back to Read only if insufficient Non-code files (YAML, JSON, MD, config) may use Read directly After discovering reusable patterns Failing to document significant patterns in memory Use write_memory to record reusable patterns for future sessions See memory_auto_creation_triggers pattern for guidance

<best_practices> Always activate project and check onboarding at session start (SERENA-B001) Always check memories with list_memories and read_memory before implementing new features (SERENA-B002) Use symbol operations (get_symbols_overview, find_symbol) over reading entire files (SERENA-B007) Use Serena symbol tools for code intelligence; use Glob/Grep/ls for filesystem navigation (SERENA-P004) Restrict searches by relative_path when scope is known to improve performance Use substring_matching for uncertain symbol names to broaden search results Record significant patterns with write_memory after discovery (SERENA-B005) Verify freshness of memories read this task via memory_staleness_verification; bump last-verified, correct, or archive as needed (SERENA-B009) Use edit_memory for updating existing memories instead of delete and recreate Follow serena_first_tool_selection decision tree for consistent tool choices Verify symbol changes with find_referencing_symbols before refactoring Follow memory_reading_by_task_type to prioritize relevant memories When a multi-language repo's language detection excludes the target file's language, fall back to Grep plus text edits instead of retrying symbol tools (symbol_tools_unavailable_fallback) </best_practices>

<anti_patterns> Reading entire files when only specific symbols are needed Use get_symbols_overview for file structure and find_symbol with include_body for specific implementations

Searching entire codebase when scope is known Use relative_path parameter to restrict search to known files or directories Implementing features without checking existing patterns Always check list_memories and read_memory before implementation Manually updating symbol references across files Use rename_symbol for consistent renaming with automatic reference updates Using high depth values unnecessarily in get_symbols_overview Start with depth=0, then incrementally increase if needed Using delete_memory without explicit user request Use edit_memory to update memories; only delete when user explicitly requests

</anti_patterns>

Always check memories before implementing new features (SERENA-B002) Use symbol operations (get_symbols_overview, find_symbol) over reading entire files (SERENA-B007, SERENA-P001) Use Serena symbol tools for code intelligence; use Glob/Grep/ls for filesystem navigation (SERENA-P004) Use Serena symbol editing (replace_symbol_body, replace_content, insert_after_symbol, insert_before_symbol, rename_symbol) for precise code modifications Record significant patterns with write_memory after discovery (SERENA-B005, SERENA-P007) Restrict searches by relative_path when scope is known Use substring_matching for uncertain symbol names Use edit_memory for updating existing memories; delete_memory only when explicitly requested by user Follow serena_first_tool_selection decision tree for tool choices Follow language_specific_symbol_operations for language-appropriate tools Follow memory_reading_by_task_type for prioritizing which memories to read Follow memory_staleness_verification for memories read during a task; leave full-index sweeps to /remember Prepare for effective Serena tool usage 1. Read Serena manual with initial_instructions 2. Activate project with activate_project 3. Verify onboarding with check_onboarding_performed 4. Check list_memories for existing patterns 5. Read relevant memories with read_memory 6. Identify target symbols or files 7. Choose appropriate tool based on decision_tree Execute Serena operations efficiently 1. Start with get_symbols_overview for file structure 2. Use find_symbol with include_body for details 3. Use find_referencing_symbols for dependencies 4. Use symbol editing tools for modifications Verify results and record patterns 1. Record new patterns with write_memory 2. Verify file correctness with get_diagnostics_for_file after edits

<error_escalation inherits="core-patterns#error_escalation"> Symbol not found with exact match Memory file not found Conflicting information in memories Memory corruption or invalid state </error_escalation>

Follow serena_first_tool_selection decision tree for tool selection Activate project and check onboarding at session start (SERENA-B001) Check memories before implementing new features (SERENA-B002) Use symbol operations over reading entire files for code (SERENA-B007) Use Serena symbol tools for code intelligence; use Glob/Grep/ls for filesystem navigation (SERENA-P004) Record significant patterns with write_memory (SERENA-B005) Restrict searches by relative_path when scope is known Reading entire files when symbol operations suffice (SERENA-P001) Unscoped searches across entire codebase Ignoring existing memory patterns (SERENA-B002 violation) Deleting memories without explicit user request (SERENA-P003) Failing to document reusable patterns in memory (SERENA-P007)

<related_skills> Investigation methodology using Serena tools Shared patterns for error escalation, decision criteria, enforcement Nix patterns stored in Serena memories TypeScript patterns stored in Serena memories Go patterns stored in Serena memories Rust patterns stored in Serena memories Common Lisp patterns stored in Serena memories Emacs patterns stored in Serena memories </related_skills>

<related_agents> Complement Serena symbol search with file-level exploration Apply Serena-retrieved context to implementation tasks </related_agents>