/sonar-analyze

name: sonar-analyze
description: Analyze a file for quality and security issues using SonarQube
argument-hint: "[file-path]"
allowed-tools: Read, Glob, Bash(git branch:*), Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*), Bash(sonar:*)

SonarQube — Code Analysis

Analyze code for quality and security issues using the SonarQube MCP Server.

Usage

sonar-analyze                        # analyze the file currently in context
sonar-analyze src/auth/login.py      # analyze a specific file

Prerequisites

This skill requires the SonarQube MCP Server to be configured and at least one of the tools `mcp__sonarqube__run_advanced_code_analysis` or `mcp__sonarqube__analyze_file_list` to be available in your session.

**Before proceeding**, verify at least one of these tools is accessible. If none are, try the CLI fallback in Step 3 before giving up — don't invent other CLI commands (e.g. `sonar mcp call` does not exist).

**If the CLI fallback also fails or doesn't apply, narrow down the cause** — check whether the `sonarqube` MCP server is enabled in this agent's configuration.

• **Not enabled / not registered** → recommend running the sonar-integrate skill.
• **Enabled but its tools are still unavailable** → configuration is correct but the server failed to start. The most common cause is that the container runtime is not running — the MCP server launches inside Docker/Podman/Nerdctl via `sonar run mcp`, so a correctly configured server still produces no tools if the daemon is stopped. Run `docker ps` yourself (falling back to `podman ps` / `nerdctl ps`) to confirm which cause applies: if it errors, the runtime is down; after the user starts it, confirm the same command succeeds before asking them to restart the agent session.

Either way, show the user:

> Unable to reach the SonarQube MCP Server. > > **Possible causes:** > - MCP server not registered — invoke the sonar-integrate skill to configure the SonarQube MCP Server, then restart the agent session > - Container runtime not running — the SonarQube MCP Server runs inside a container (Docker, Podman, or Nerdctl); start your container runtime, then restart the agent session > - Credentials not configured — invoke the sonar-integrate skill > - Project key missing or invalid — pass an explicit key if needed, verify `sonar-project.properties`, or re-run the sonar-integrate skill for this project

Then ask the user (yes/no) whether to run the sonar-integrate skill now. Briefly explain what it does: it checks the SonarQube setup on their machine — installing or updating `sonarqube-cli` and verifying authentication — and re-configures the integration for this agent, including the SonarQube MCP server and secrets-scanning hooks. If they confirm, invoke the sonar-integrate skill yourself and follow it end-to-end in this session, then ask the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running and to restart the agent session so the new MCP tools become available; if they decline, stop.

Instructions

Step 1: Resolve what to analyze

Both analysis tools work on **one file at a time**. Resolve a single file path:

• If the user provided a file path, use it.
• If no path was provided, look at the current conversation context for a recently mentioned or edited file.
• If nothing is clear, ask: *"Which file would you like me to analyze?"*

Do not accept a directory as input. If the user provides one, ask them to specify a single file.

Step 2: Read the file and determine its scope

1. Read the file's full content — only needed as a fallback for `run_advanced_code_analysis`'s `fileContent` parameter (see Step 3). 2. Determine the file scope: `"TEST"` or `"MAIN"`. Use the file path to deduce the scope. For example, if the file path contains `test`, `spec`, or `__tests__`, it's likely `"TEST"` scope.

Step 3: Call the appropriate analysis tool

After running the sonar-integrate skill, the SonarQube MCP Server often has a **default project** for this workspace, so **`projectKey` is sometimes unnecessary** — pass it only when the tool schema requires it or the user targets another project.

Two tools may be available depending on whether the connected organization is eligible for Vortex analysis:

**Try `mcp__sonarqube__run_advanced_code_analysis` first** (available when the organization is eligible for Vortex analysis).

Before calling it, detect the current branch name using `git branch --show-current`. If git is unavailable, use `main` as a fallback.

Then call with:

• `projectKey` — **omit unless the tool requires it** (initial MCP configuration usually supplies the default project); if required, use the value from the user's arguments if provided, otherwise `sonar.projectKey` in `sonar-project.properties` at the repo root
• `branchName` — detected branch name
• `filePath` — project-relative file path (e.g. `src/auth/login.py`)
• `fileContent` — full file content; **only pass if the tool requires it** (when the MCP server has a mount, it reads the file directly and this parameter will not be required)
• `fileScope` — `["TEST"]` or `["MAIN"]`

**If that tool is unavailable, fall back to `mcp__sonarqube__analyze_file_list`** (requires a running SonarQube for IDE instance bridged to this session):

• `file_absolute_paths` — array containing the absolute path to the file (e.g. `["/home/user/project/src/auth/login.py"]`); resolve it from the file path found in Step 1

**If neither MCP tool is available, fall back to the CLI's Vortex analysis:**

sonar analyze agentic --file <file-path> [--file <other-file-path> ...] --format json [--branch <branch-name>] [-p <project-key>]

Same backend as `run_advanced_code_analysis` (repeatable `--file` covers multi-file too), and the practical fallback for `analyze_file_list` as well — it has no direct CLI equivalent, but this achieves the same goal.

Requires a Vortex analysis-eligible organization. If the org isn't eligible, or `sonar` isn't