Agent-Skills.md

Agent Skills: Serena MCP Integration

Serena MCP integration for file I/O, semantic code editing, and persistent memory. ALWAYS use Serena for file operations and language server features when available. Proactively sync memories at phase/todo/session boundaries.

UncategorizedID: tianjianjiang/smith/smith-serena

Repository

tianjianjiang/smith
tianjianjiang
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/tianjianjiang/smith/tree/HEAD/smith-serena

Skill Files

Browse the full folder contents for smith-serena.

Download Skill

Loading file tree…

smith-serena/SKILL.md

Skill Metadata

Name
smith-serena
Description
Serena MCP integration. ALWAYS load before any Serena tool call or memory write. Use when a prompt mentions Serena, and at phase and session boundaries to sync memories.

Serena MCP Integration

Prerequisites: None (standalone reference)

CRITICAL: Serena-First Principle

When Serena MCP is available, prefer Serena for:

  1. File I/O - All file reading and writing operations
  2. Language server features - Symbols, references, navigation, semantic editing
  3. Persistent memory - Cross-session and cross-context-reset persistence

Tool Preference Order:

  1. find_symbol, get_symbols_overview - Reading code (semantic)
  2. search_for_pattern - Reading with regex patterns
  3. replace_content (regex mode) - Editing code
  4. replace_symbol_body - Replacing function/class bodies
  5. find_referencing_symbols - Navigation, impact analysis
  6. write_memory, read_memory - Persistent context
  7. Platform native tools - fallback when Serena is unavailable or has no tool for the operation

Prefer Serena over platform native tools when available:

  • Native file read tools may truncate large files silently
  • String-based replace tools fail on duplicate content
  • Text-based search is less efficient than semantic search

Why Serena Over Native Tools

Serena advantages:

  • Semantic symbol operations reduce context usage by 99%+
  • Regex mode handles complex replacements reliably
  • Memory files persist across sessions and context resets
  • Language server integration provides accurate navigation
  • No silent truncation or string-matching failures

Native Write vs Symlinked Paths

Native Edit/Write do NOT refuse symlinked targets — they write via an atomic temp-file + rename. Through a directory symlink (e.g. ~/.claude/skills → the smith repo) the rename lands in the resolved dir, so the link and the real file are fine. But a file-level symlink is silently replaced by a regular file — the link breaks and the original diverges (a confirmed Claude Code defect, references/SOURCES.md). smith SKILL.md files are plain files, so editing them via either path is safe; the hazard is any path that is itself a file symlink.

  • Before a native write, if the target file may be a symlink, resolve it (readlink -f / write the real path) — do not write the link path.
  • Distinct from Serena paths inside a worktree (@smith-worktree/SKILL.md); that is about which checkout a Serena path resolves to, not symlink replacement.

Serena Activation Workflow

Launch mode determines activation:

Single-Project Auto-Activation (Default)

Claude Code with --project-from-cwd activates projects automatically from working directory.

At session start:

  1. initial_instructions() — Load Serena manual (once per conversation)
  2. onboarding() — Check setup (returns instructions if needed)
  3. list_memories() — Discover available context
  4. read_memory() — Load project context

Worktrees and Serena's Root

Hook details: references/HOOKS.md.

  • Session started in a worktree: Serena roots there; link-worktree-memories links its .serena/memories to the primary's.
  • EnterWorktree mid-session: Serena stays rooted at the primary. Prefix Serena paths and globs: .claude/worktrees/«name»/src/app.ts. worktree-path-guard blocks one lacking it; an unreachable worktree (e.g. gitignored) takes built-in Edit/Write.

Multi-Project / Global MCP

Without --project-from-cwd, manual activation required.

At session start:

  1. initial_instructions() — Load manual
  2. activate_project(name_or_path) — Activate specific project
  3. list_memories() — Discover context
  4. read_memory() — Load context

Core Serena Tools

Reading

  • get_symbols_overview(path, depth=1) - File structure first
  • find_symbol(pattern, path, include_body=false) - Locate symbols (MyClass/get*)
  • search_for_pattern(regex, path) - Content search with context

Writing

  • replace_content(path, needle, repl, mode="regex") - Pattern replace
  • replace_symbol_body(name, path, body) - Replace function/class (includes signature)
  • insert_after_symbol / insert_before_symbol - Add new code

Navigation

  • find_referencing_symbols(name, path) - All references to symbol

Proactive Memory Workflow

Memory files persist across sessions and context resets. Sync proactively at boundaries.

Location: .serena/memories/

Session Start:

  1. list_memories() - Discover available context
  2. read_memory() - Load project_overview, session_summary, relevant task memories

Phase/Todo Boundaries (PROACTIVE):

  • Before starting phase/todo: read_memory() for relevant context
  • After completing phase/todo: write_memory() with findings, decisions, blockers
  • On status change: Update task_completion memory with progress

Before Context Reset (at platform's critical threshold):

  • write_memory() - Save full session state, current task, next steps

Session End:

  • write_memory() - Continuity notes: what was done, what's next, blockers

Memory Naming Conventions:

  • project_overview - High-level project context (read at start)
  • session_summary - Current session progress (update frequently)
  • task_completion - Completed task tracking (update on todo completion)
  • {feature}_notes - Feature-specific context
  • {task}_context - Task-specific discoveries and decisions

Stores are not a uniform layout — do not assume one path scheme:

  • Serena: .serena/memories/*.md (flat dir; naming = memory key).
  • Basic-Memory: own store (markdown files) backed by a SQLite index; reach it via its MCP tools, not by path.

Read each store through its own tool; a path that works for one will not resolve the others.

Conflicting memories → reconcile against source, not against each other. When stores (or an older vs. newer memory) disagree, treat the current code/config/docs as the source of truth and the memory as a possibly-stale pointer; verify before acting, and update or supersede the stale entry. File-backed entries that drift from their source are already staleness-flagged — honor the flag.

Project Configuration

Location: .serena/project.yml

Standard Project

project_name: my_project
language: python  # or typescript, java, etc.

Documentation Project (No Code)

project_name: my_docs
language: markdown

For projects with no code files, specify language: markdown explicitly to avoid onboarding errors.

Testing Serena Availability

To verify Serena MCP is available:

list_memories()
  • If successful: Serena is available; prefer Serena tools
  • If fails: Fall back to platform native tools with caution

Before You Finish

Serena-first for all file operations:

  1. Test availability: list_memories()
  2. Use Serena tools for file I/O and language server features
  3. Fall back to platform native tools when Serena is unavailable or has no tool for the operation

Workflow for code tasks:

  1. read_memory() - Load relevant context before starting
  2. get_symbols_overview - Understand file structure
  3. find_symbol - Locate target symbols
  4. replace_symbol_body or replace_content - Make changes
  5. write_memory() - Persist discoveries after completing

Periodic memory sync:

  • Phase start → read_memory()
  • Phase end → write_memory()
  • Todo start → read_memory() if context needed
  • Todo complete → write_memory() with findings

Ralph Loop Memory Integration

Serena persists Ralph state: ralph_«task»_state with iteration, hypotheses, test_results, next_action.

Sync: After each iteration; before/after context reset. See @smith-ralph/SKILL.md.

Related

  • @smith-ctx/SKILL.md - Context management thresholds
  • @smith-guidance/SKILL.md - AI agent behavior patterns
  • @smith-ctx-kiro/SKILL.md - Kiro-specific: Serena is MANDATORY over native tools
Serena MCP Integration Skill | Agent Skills