serena-config

Q: How do I install serena-config?

Run npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill serena-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/serena-config/ (personal) or .claude/skills/serena-config/ (project).

by paulnsorensenBackend & APIs

Configure the Serena MCP server — its global defaults and a repo's per-project settings. Use when the user says "configure serena", "set up serena for this repo", "serena project config", "serena global config", "tune serena for this codebase", "edit serenaconfig.yml", "edit project.yml", "monorepo serena", "serena picked the wrong language", "serena is indexing vendor/nodemodules", "make serena read-only here", "serena contexts and modes", "what context for claude-code", "disable serena memory/onboarding", "point serena at my installed language server", "lsspecificsettings", "lspath", "SERENAHOME", or "move the .serena folder". Routes per-repo .serena/project.yml questions to references/project-config.md and machine-wide /.serena/serenaconfig.yml (settings, contexts, modes, language-server tuning) to references/global-config.md. Do NOT use for general "use serena to find / edit X" routing — that is an MCP-routing concern, not configuration.

Installs: 57
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill serena-config

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads serena-config automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

serena-config

Configure Serena across its two layers: the machine-wide global config and a repo's per-project config.

Serena is configured in layers, each overriding or extending the one above:

Global — ~/.serena/serena_config.yml. Defaults for every project: language backend, default tools/modes, global ignore rules, language-server tuning.
Project — <repo>/.serena/project.yml. Per-repo overrides: languages, ignore rules, write access, monorepo workspace folders, added modes.
Contexts & modes — composable toolset/prompt presets, set globally, per-project, or at startup.
CLI args to serena start-mcp-server — override or extend everything above.

<certain> Many project.yml keys extend or override serena_config.yml. Put machine-wide defaults in the global file; put only repo-specific aspects in the project file.

Route to the right reference

The user wants to…	Read
Tune a single repo: wrong language, monorepo cross-refs, ignore `vendor/`/generated dirs, read-only repo, per-repo LSP path	`references/project-config.md`
Create / index / activate a project; understand `project.local.yml` local overrides	`references/project-config.md`
Set machine-wide defaults: language backend, default tools/modes, global ignore, logging	`references/global-config.md`
Pick or change a context (`claude-code`, `ide`, `desktop-app`, …)	`references/global-config.md`
Add / override modes (`planning`, `editing`, `no-memories`, `query-projects`, …)	`references/global-config.md`
Point Serena at a self-installed language server (`ls_path`) or pin an LSP version	`references/global-config.md`
Move the data directory (`SERENA_HOME`) or the per-project `.serena` folder	`references/global-config.md`

When to act (and when not to)

Serena auto-creates both config files with sensible defaults — global on first run, project on first activation of a repo. Most repos need no edits. Touch a config only when one of these is true:

Symptom	Layer	Fix lives in
LSP can't resolve symbols across package boundaries (monorepo)	project	`additional_workspace_folders`
`find_symbol` returns wrong-language results or LSP errors at startup	project	`languages:`
Symbol search floods from `vendor/`, `node_modules/`, `dist/`, generated code	project	`ignored_paths:`
Repo is review-only and Serena should not write	project	`read_only: true`
Wrong toolset for the harness (e.g. Claude Code duplicating built-ins)	global	`--context`
Want planning-only or memory-free behavior	global	modes
Self-installed LSP, or need to pin an LSP/runtime version	either	`ls_specific_settings`

If none apply, leave the config alone — the bootstrap is correct.

The one proactive exception — ignored_paths. Unlike the rows above, this is worth setting before you feel pain in any repo that commits vendored or generated code (vendor/, checked-in dist/, generated clients, snapshot fixtures). .gitignore is honored by default, but committed noise pollutes find_symbol / get_symbols_overview (and can cut the LSP's initial indexing). See references/project-config.md § "ignored_paths — set this in most non-trivial repos". ls_path, by contrast, stays an escape hatch — managed-first is the recommended default (see references/global-config.md).

Editing discipline

Never hand-create a config from scratch. Let Serena bootstrap it (serena project create for a project, first run for the global file), then edit. The generated files carry inline documentation comments and fields added by newer versions — preserve them.
Verify after editing. serena print-system-prompt "$(pwd)" renders the resolved config; confirm the project name, language list, active modes, and excluded tools are what you expect. Then probe the LSP with a find_symbol call against a known symbol — a clean record means the languages parsed; an LSP startup error means languages: or ls_specific_settings: is wrong.
On LSP weirdness after a change, delete .serena/cache/ to force a rebuild; some servers also need the MCP server restarted to fully reset.

References

Project config schema (template): https://github.com/oraios/serena/blob/main/src/serena/resources/project.template.yml
Global config schema (template): https://github.com/oraios/serena/blob/main/src/serena/resources/serena_config.template.yml
Language enum (valid languages: / ls_specific_settings keys): https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
Workflow docs: https://oraios.github.io/serena/02-usage/040_workflow.html
Configuration docs: https://oraios.github.io/serena/02-usage/050_configuration.html

FAQ

What does the serena-config skill do?

How do I install serena-config?

Run npx skills add https://github.com/paulnsorensen/skillz-that-grillz --skill serena-config in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/serena-config/ (personal) or .claude/skills/serena-config/ (project).

Which AI agents can use serena-config?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is serena-config safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains serena-config?

It is published by paulnsorensen in paulnsorensen/skillz-that-grillz. It has 57 recorded installs.