Guide for setup Serena MCP server for semantic code retrieval and editing capabilities
48
36%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/mcp/skills/setup-serena-mcp/SKILL.mdQuality
Discovery
22%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is too vague and reads more like a document title than a functional skill description. It lacks concrete actions, explicit trigger conditions, and natural user keywords. The mention of 'Serena MCP server' provides some distinctiveness but the overall description fails to communicate when Claude should select this skill.
Suggestions
Add a 'Use when...' clause specifying trigger conditions, e.g., 'Use when the user wants to set up Serena, configure MCP servers for code intelligence, or needs semantic code search and navigation.'
List specific concrete actions the skill covers, e.g., 'Guides installation and configuration of the Serena MCP server, including setting up semantic indexing, symbol search, code navigation, and editing workflows.'
Include natural user keywords like 'code search', 'code navigation', 'symbol lookup', 'code intelligence', 'MCP setup', and 'Serena configuration' to improve trigger term coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description says 'setup Serena MCP server for semantic code retrieval and editing capabilities' which is vague — it mentions 'semantic code retrieval and editing' but doesn't list concrete actions like indexing, searching symbols, refactoring, or navigating code structures. | 1 / 3 |
Completeness | The description partially addresses 'what' (setup guide for Serena MCP server) but has no explicit 'when' clause or trigger guidance. The lack of a 'Use when...' clause caps this at 2 per the rubric, and the 'what' itself is weak, so it scores 1. | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'Serena', 'MCP server', 'semantic code retrieval', and 'editing', but misses common user terms like 'code search', 'code navigation', 'symbol lookup', or 'code intelligence'. The term 'Serena' is a specific product name which helps, but 'setup' narrows the scope. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Serena MCP server' is fairly specific and distinguishes it from generic coding skills, but 'semantic code retrieval and editing capabilities' could overlap with other code search or editing tools. The 'setup' framing helps narrow it somewhat. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable framework for guiding Serena MCP setup but relies too heavily on external documentation for the actual actionable steps, making it more of a meta-guide than a concrete skill. The workflow is logically sequenced but lacks robust validation/error recovery paths. The CLAUDE.md template content is well-defined and copy-paste ready, which is a strength, but the core setup instructions would benefit from concrete commands and configuration examples.
Suggestions
Include concrete configuration examples (e.g., actual MCP client config JSON for Claude Code) instead of relying entirely on external URLs, which may be unavailable or change.
Add explicit error recovery steps for common failure scenarios (e.g., 'If Serena tools are not accessible after restart, check X, verify Y, try Z').
Move the CLAUDE.md template content to a separate bundle file (e.g., CLAUDE_TEMPLATE.md) and reference it, reducing the main skill's length.
Add the actual 'serena project create --index' command and 'uv' installation command directly in the workflow steps rather than deferring to external docs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some unnecessary verbosity. Step 3 delegates to external URLs rather than inlining key info (good), but the CLAUDE.md template content and the restart message are somewhat lengthy. Some instructions like 'Guide user through setup process' are padded with obvious sub-steps. The repeated 'if not already setup/configured' phrases add minor bloat. | 2 / 3 |
Actionability | The skill provides a structured process but relies heavily on external documentation (URLs) for the actual setup commands and configuration details. It lacks concrete, executable commands for most steps—e.g., no actual MCP configuration JSON/YAML examples, no specific 'uv' installation commands, no 'serena project create --index' shown in the main workflow. The CLAUDE.md content to write is concrete and copy-paste ready, but the core setup guidance is vague. | 2 / 3 |
Workflow Clarity | Steps are numbered and sequenced logically (determine context → check existing → load docs → setup → update CLAUDE.md → initialize). However, validation checkpoints are weak—step 4.7 mentions 'Test connection' but the feedback loop for failure is unclear. The restart instruction is explicit which is good, but there's no clear error recovery path if Serena tools remain inaccessible after restart. Step 6 feels redundant with step 4.4-4.5. | 2 / 3 |
Progressive Disclosure | The skill references external URLs for detailed documentation (good delegation), but there are no bundle files to support it. The skill itself is somewhat monolithic—the CLAUDE.md template content and restart message are inlined rather than referenced. For a skill with no bundle, the organization is acceptable but the inline templates make it longer than necessary. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
dedca19
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.