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	2.0.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 Regex search across codebase Regex pattern Restrict search scope Lines before match Lines after match Search only code files or all files Glob pattern for files to include Glob pattern for files to exclude Find patterns, search non-code files, complex regex searches List directory contents Directory path Include subdirectories Explore directory structure Find files by name pattern File name pattern to search Restrict search scope Locate files by name 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 Validate search quality and completeness After 3+ search operations to assess information sufficiency Verify alignment with task before code modification Mandatory before any symbol editing operation Confirm task completion Mandatory before reporting task completion to user 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 {project}-conventions # Project-wide conventions {feature}-patterns # Feature-specific patterns {domain}-patterns # Domain-specific patterns architecture-{decision} # Architecture decisions 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 Meta-cognitive tools for ensuring search quality and task alignment at mandatory checkpoints After 3+ search operations think_about_collected_information

  <note>Before making code changes</note>
  think_about_task_adherence

  <note>When task seems complete</note>
  think_about_whether_you_are_done
</example>

Initialize Serena at session start Step 1: Activate project Workflow guidance Step completed activate_project project="project-name"

  <step order="1">

Step 2: Verify onboarding Workflow guidance Step completed check_onboarding_performed

  <step order="1">

Step 3: If not onboarded, run onboarding Workflow guidance Step completed onboarding (if needed)

  <step order="1">

Step 4: Check available memories Workflow guidance Step completed list_memories

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

  <step order="1">

Step 2: Explore class members Workflow guidance Step completed get_symbols_overview relative_path="src/main.ts" depth=1

  <step order="1">

Step 3: Get specific implementation Workflow guidance Step completed find_symbol name_path_pattern="MyClass/myMethod" include_body=true

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

  <step order="1">

Step 2: Find all callers Workflow guidance Step completed find_referencing_symbols name_path="processData" relative_path="src/processor.ts"

  <step order="1">

Step 3: Recursively trace for full dependency graph Workflow guidance Step completed Repeat steps 1-2 for each caller to build complete dependency tree

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

  <step order="1">

Step 2: Identify all usages Workflow guidance Step completed find_referencing_symbols name_path="MyClass/oldMethod" relative_path="src/myclass.ts"

  <step order="1">

Step 3: Call think_about_task_adherence Workflow guidance Step completed think_about_task_adherence

  <step order="1">

Step 4: Perform the change Workflow guidance Step completed replace_symbol_body name_path="MyClass/oldMethod" relative_path="src/myclass.ts" body="..."

  <step order="1">

Step 5: Update references if interface changed Workflow guidance Step completed If method signature changed, update all calling sites identified in step 2

Search for patterns with appropriate scope Search only in code files search_for_pattern substring_pattern="TODO:" restrict_search_to_code_files=true

  <note>Search in all files including configs</note>
  search_for_pattern substring_pattern="api-key" restrict_search_to_code_files=false

  <note>Include context around matches</note>
  search_for_pattern substring_pattern="function.\*async" context_lines_before=2 context_lines_after=3
</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 Memory versioning, archival, and consolidation patterns 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

<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 search_for_pattern Use list_dir Use find_file </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 search_for_pattern with regex 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 </decision_tree>

<decision_tree name="serena_first_tool_selection"> Serena-first tool selection hierarchy with explicit fallback conditions What type of search or code operation is needed? Use Serena find_file Use Glob Use Serena search_for_pattern Use Grep Use Serena list_dir Use Bash ls Use Serena get_symbols_overview (depth=0 first, then depth=1) Use Read with offset/limit Use Serena find_symbol with name_path_pattern Use find_symbol with substring_matching=true Use Grep 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 <unavailable_conditions> Serena project not activated (call activate_project first) File type not supported by LSP (use search_for_pattern or Read) 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 search_for_pattern for structured search Use Read for full context when structure is complex Use search_for_pattern or Read Symbol operations less useful for prose </decision_tree>

Session start 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 Before symbol editing Call think_about_task_adherence Task adherence check recorded Before reporting completion Call think_about_whether_you_are_done Completion check recorded 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 After search sequence of 3+ operations (find_symbol, search_for_pattern, get_symbols_overview, Grep, Glob) Call think_about_collected_information Search quality validation recorded 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 Always Reading entire files when symbol operations suffice Use get_symbols_overview and find_symbol instead Always Modifying code without think_about_task_adherence Call think_about_task_adherence first Always Deleting memories without explicit user request Use edit_memory instead or ask user permission Always Using Glob/Grep/Read when Serena navigation tools available Use Serena list_dir, find_file, search_for_pattern, get_symbols_overview, find_symbol first Glob/Grep/Read allowed only when: Serena project not activated, tool explicitly fails, or file type not supported Before final response to user Completing task without calling think_about_whether_you_are_done Call think_about_whether_you_are_done before final response 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) Call think_about_task_adherence before any code modification (SERENA-B003) Call think_about_collected_information after 3+ search operations (SERENA-B006) Call think_about_whether_you_are_done before final response (SERENA-B004) Use Serena navigation tools before Glob/Grep/Read (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) Use edit_memory for updating existing memories instead of delete and recreate Follow serena_first_tool_selection decision tree for consistent tool choices Use context_lines parameters in search_for_pattern to understand surrounding code Verify symbol changes with find_referencing_symbols before refactoring Follow memory_reading_by_task_type to prioritize relevant memories </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 Modifying code without calling think_about_task_adherence Always call think_about_task_adherence before symbol editing operations Using delete_memory without explicit user request Use edit_memory to update memories; only delete when user explicitly requests Using Glob/Grep tools when Serena navigation tools are available Prefer Serena list_dir, find_file, search_for_pattern for codebase exploration 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) Call think_about_collected_information after search sequences of 3+ operations (SERENA-B006) Call think_about_task_adherence before making code changes (SERENA-B003) Call think_about_whether_you_are_done before final response (SERENA-B004, SERENA-P005) Use Serena navigation tools (find_file, search_for_pattern, list_dir) before Glob/Grep/Read (SERENA-P004) Use Serena symbol editing (replace_symbol_body, 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 Prepare for effective Serena tool usage 1. Activate project with activate_project Workflow guidance Step completed 2. Verify onboarding with check_onboarding_performed Workflow guidance Step completed 3. Check list_memories for existing patterns Workflow guidance Step completed 4. Read relevant memories with read_memory Workflow guidance Step completed 5. Identify target symbols or files Workflow guidance Step completed 6. Choose appropriate tool based on decision_tree Workflow guidance Step completed Execute Serena operations efficiently 1. Start with get_symbols_overview for file structure Workflow guidance Step completed 2. Use find_symbol with include_body for details Workflow guidance Step completed 3. Use find_referencing_symbols for dependencies Workflow guidance Step completed 4. Call think_about_task_adherence before edits Workflow guidance Step completed 5. Use symbol editing tools for modifications Workflow guidance Step completed Verify results and record patterns 1. Call think_about_collected_information after searches Workflow guidance Step completed 2. Record new patterns with write_memory Workflow guidance Step completed 3. Call think_about_whether_you_are_done when complete Workflow guidance Step completed

<error_escalation> Symbol not found with exact match Retry with substring_matching=true, note in report, proceed Memory file not found Document issue, ask user for clarification Conflicting information in memories STOP, present options to user Memory corruption or invalid state BLOCK operation, require explicit user acknowledgment </error_escalation>

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) Call think_about_task_adherence before code modifications (SERENA-B003) Call think_about_collected_information after 3+ search operations (SERENA-B006) Call think_about_whether_you_are_done before final response (SERENA-B004) Use Serena navigation tools before Glob/Grep/Read (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) Using Glob/Grep/Read when Serena navigation tools are available (SERENA-P004) Skipping reflection checkpoints at mandatory points (SERENA-P005) 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>