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

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 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.

Serena MCP Integration

Load if: Serena MCP available, file operations needed, symbol-level editing Prerequisites: None (standalone reference)

CRITICAL: Serena-First Principle

When Serena MCP is available, ALWAYS use 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 ONLY when Serena unavailable

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 (Claude Code issue #40857, confirmed). 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 the worktree MCP write blind spot in @smith-worktree/SKILL.md; that is about Serena writes hitting the main checkout, not symlink replacement.

Serena Activation Workflow

At session start, MUST activate Serena:

  1. activate_project() - Activate the project
  2. check_onboarding_performed() - Verify onboarding status
  3. list_memories() - Discover available context
  4. read_memory() - Load relevant project context

If onboarding not performed:

  • Call onboarding() to get instructions
  • Follow onboarding steps before proceeding

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

Relationship with auto memory: Auto memory handles long-term project knowledge (patterns, conventions). Serena memory handles session state and cross-context continuity. See @smith-ctx-claude/SKILL.md for delineation.

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

  • Serena: .serena/memories/*.md (flat dir; naming = memory key).
  • Claude Code auto memory: ~/.claude/projects/«project-slug»/memory/ — flat *.md files plus a MEMORY.md index that wiki-links the rest.
  • 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, use Serena tools exclusively
  • 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 ONLY if Serena unavailable

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