Serena

Use Serena-backed semantic code navigation and editing when working in existing software projects with non-trivial structure, especially multi-file repos where symbol-aware lookup and targeted edits are more reliable and token-efficient than brute-force file reading. Use when the environment exposes Serena tools such as project activation, symbol lookup, reference search, semantic search, file reads, directory listing, file finding, or symbol-scoped edits.

Use Serena as the first choice for understanding and editing existing codebases when the necessary tools are available.

What this skill is for

Use this skill when another agent needs to integrate Serena into its normal coding workflow instead of treating the repo as a pile of text files.

Aim for this behavior:

• activate the project once
• inspect structure semantically before reading large files
• trace references before editing
• prefer symbol-scoped edits when possible
• fall back to normal file tools only when Serena is missing a capability or fails

For extra examples and trigger patterns, read references/integration-patterns.md.

Core workflow

1. Resolve the target project path.
2. Call serena_activate_project.
3. Start with structure discovery:
   • serena_project_overview
   • serena_find_symbol
   • serena_list_dir
   • serena_find_file
   • serena_session_status when you need to inspect active Serena sessions
4. Narrow scope with:
   • serena_find_references
   • serena_search_pattern
   • serena_read_symbol
   • serena_read_file
5. Prefer semantic edits when changing existing code:
   • serena_replace_symbol_body
   • serena_insert_before_symbol
   • serena_insert_after_symbol
   • serena_rename_symbol
6. Use broader edit tools only when symbol-scoped tools are not a good fit:
   • serena_replace_content
   • serena_create_text_file
7. Use serena_execute_shell_command only as an advanced escape hatch when project-context shell execution is genuinely the right tool.
8. Use serena_call_tool only when the normalized surface does not cover the needed Serena capability.
9. Fall back to ordinary file tools only when Serena cannot answer safely or reliably.

When Serena is worth the overhead

Prefer Serena when:

• the project spans multiple files
• the user asks about references, call chains, or symbol relationships
• the user wants a precise edit to an existing class, function, method, or module
• reading whole files would be noisy or wasteful
• the repo already has real structure and semantic lookup is available

Skip or delay Serena when:

• the task is a tiny one-file change and the target location is already obvious
• you are creating a brand-new file with little dependency on existing code
• Serena is unavailable or failing and direct file tools are simpler
• the user already provided the exact file region and semantic lookup adds no value

Tool preference order

For existing codebases, prefer this order:

1. serena_activate_project
2. serena_project_overview / serena_find_symbol / serena_find_file
3. serena_find_references / serena_search_pattern
4. serena_read_symbol / serena_read_file
5. symbol-scoped edit tools
6. broader Serena edit tools
7. serena_session_status for session inspection/debugging
8. serena_execute_shell_command only when semantic tools are not the right mechanism
9. fallback to read, edit, and exec only when needed

Integration guidance for agent authors

When you want another agent to use Serena well, instruct it to:

• activate the project before semantic reads or edits
• inspect symbols and references before modifying code
• use normalized Serena tools first
• keep edits narrow and structured
• avoid whole-file rewrites when a symbol-scoped edit is possible
• treat passthrough as an escape hatch, not the default workflow

A good instruction pattern is:

Use Serena on the repo. Start with serena_activate_project, then narrow scope with serena_find_symbol, serena_find_references, and serena_read_symbol before editing.

Practical usage patterns

Understand a repo area

Use this sequence:

1. serena_activate_project
2. serena_find_file or serena_list_dir
3. serena_project_overview
4. serena_find_symbol
5. serena_read_symbol

Trace impact before changing code

Use this sequence:

1. serena_find_symbol
2. serena_find_references
3. serena_search_pattern if naming or text-level usage matters
4. serena_read_symbol for the most relevant callers/callees

Make a targeted edit

Use this sequence:

1. locate the exact symbol
2. read the symbol body
3. inspect references if behavior changes could ripple outward
4. choose the narrowest valid edit tool
5. re-read the changed symbol or nearby references when confidence is low

Editing rules

• Keep edits as narrow as possible.
• Prefer symbol-targeted edits over text replacement across a whole file.
• Prefer semantic rename over manual multi-file rename logic.
• Re-read the relevant symbol or references after a material edit when confidence is low.
• If semantic identity is ambiguous, do not guess; disambiguate using path or extra lookup.
• In read-only mode, do not attempt mutating Serena tools.

Safety and fallback behavior

If Serena fails:

1. Explain briefly what failed.
2. Fall back to standard file-based workflow.
3. Keep using the smallest possible read/edit scope.
4. Do not pretend the semantic result was confirmed if it was not.

If a raw Serena passthrough tool is available:

• use it only when the normalized tool surface does not cover the needed capability
• prefer stable normalized tools for repeated workflows
• avoid passthrough for routine actions that already have a clear normalized tool