Serena

Use Serena-backed semantic code navigation and editing when working in existing software projects with non-trivial structure, especially multi-file repos whe...

Security Scan

This is an instruction-only skill that teaches an agent how to use Serena semantic code navigation and edits; it asks for no installs, credentials, or config and is internally consistent with its stated purpose.

Purpose & Capability

The name/description (semantic code navigation and targeted edits) matches the instructions: all operations are Serena-themed (activate project, find symbols, read symbol/file, symbol-scoped edits). The skill does not request unrelated binaries, credentials, or install steps.

Instruction Scope

The SKILL.md stays within repo-oriented semantic operations (symbol lookup, reference tracing, narrow edits). It does allow use of serena_execute_shell_command and passthrough tools as an escape hatch; that is coherent for a project-context tool but is a higher-risk capability if the underlying Serena plugin exposes shell execution—the skill itself does not instruct reading unrelated env vars or exfiltrating data.

Install Mechanism

There is no install spec and no code files — instruction-only skills are low-risk because nothing is fetched or written by the skill itself.

Credentials

The skill does not request environment variables, credentials, or config paths. All required capabilities are Serena tool calls; there are no disproportionate secret or cross-service requests.

Persistence & Privilege

always:false and default invocation settings are used. The skill does not request persistent privileges or changes to other skills or system-wide configs.

Assessment

This skill is coherent and conservative: it only teaches how to use Serena tools and requests no credentials or installs. Before enabling: ensure the Serena plugin/tooling your agent will call is trustworthy (it is the component that would perform file reads, edits, or any shell commands), restrict or review use of serena_execute_shell_command if you are concerned about running project-context shell commands, and confirm the agent has only the repository access you intend (the skill assumes a Serena provider exists but does not install one). If you want extra caution, test the workflow on a non-sensitive repo and audit the actual Serena tool implementations that will be invoked.

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