SonarQube

View saved version →

---
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:**

```bash
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 installed/authenticated, show the standard message from Prerequisites — don't guess further commands.

### Step 4: Format the results

**If issues are found**, present them as a table sorted by line number:

```markdown
## SonarQube Analysis — `src/auth/login.py`

Found **3 issue(s)**:

| Line | Severity  | Rule         | Message                                               |
| ---- | --------- | ------------ | ----------------------------------------------------- |
| 12   | 🔴 Blocker | python:S2077 | Make sure that executing this SQL query is safe here. |
| 34   | 🟠 Major   | python:S1481 | Remove the unused local variable "token".             |
| 67   | 🟡 Minor   | python:S1135 | Complete the task associated to this "TODO" comment.  |
```

Severity icons (the label depends on the server version):
- 🔴 Blocker
- 🟠 Critical / High
- 🟡 Major / Medium
- 🔵 Minor / Low
- ⚪ Info

**If no issues are found**:

```markdown
## SonarQube Analysis — `src/auth/login.py`

✅ No issues found.
```

### Step 5: Next steps

After the results, always add:

- If issues were found: *"Invoke the sonar-fix-issue skill with `<rule> <file>:<line>` to fix a specific issue, or ask me to fix them all."*
- If the user wants to analyze another file: remind them to invoke the sonar-analyze skill with the file path.

View saved version →

---
name: sonar-coverage
description: Find files with low test coverage and inspect uncovered lines in a SonarQube project (project key optional when MCP integration already defines the default project)
argument-hint: "[project-key?] [--max n] [--file key] [--pr id]"
allowed-tools: Read, Grep, Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*), Bash(sonar:*)
---

# SonarQube — Coverage

Identify files with insufficient test coverage and pinpoint the exact lines that need tests.

## Usage

```
sonar-coverage                              # worst-covered files in the current project
sonar-coverage my-project                   # worst-covered files in a specific project
sonar-coverage my-project --max 50          # only files with coverage <= 50%
sonar-coverage my-project --file src/auth/login.py  # line-by-line detail for one file
```

## Prerequisites

This skill requires the SonarQube MCP Server to be configured and the tools `mcp__sonarqube__search_files_by_coverage` and `mcp__sonarqube__get_file_coverage_details` to be available in your session.

**Before proceeding**, verify the tools are accessible. If they are not, try the `sonar api` CLI fallback in Step 3 before giving up — don't invent other CLI commands (e.g. `sonar mcp call` or `sonar coverage` do not exist).

**If the CLI fallback also fails (for example `sonar` not installed/authenticated, or no project key can be resolved), 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, or project key not found.
>
> **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 is wrong or no default project in MCP config — pass an explicit key, or verify `sonar-project.properties` / 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 the project key (only when needed)

MCP tools sometimes **do not require** `projectKey` after the sonar-integrate skill has stored the default project for this workspace. Resolve a key only when you must pass it (tool schema requires it, or the user targets another project):

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **omit `projectKey`** in MCP calls and rely on the integration default.

### Step 2: Parse optional flags from the user-provided arguments

| Flag           | Meaning                                                                     |
| -------------- | --------------------------------------------------------------------------- |
| `--max <n>`    | Only return files with coverage ≤ n% (maps to `maxCoverage`)                |
| `--pr <id>`    | Analyse a pull request instead of the main branch                           |
| `--file <key>` | Skip the file list and go straight to line-by-line detail for this file key |

### Step 3: Run the appropriate flow

#### Flow A — File list (default, no `--file`)

Call `mcp__sonarqube__search_files_by_coverage`. Include **`projectKey` only if** you resolved one in Step 1 **and** the tool requires it; otherwise omit it.

```json
{
  "projectKey": "<only-if-required>",
  "maxCoverage": <n>,       // if --max was given
  "pullRequest": "<id>",    // if --pr was given
  "pageSize": 20
}
```

Omit `projectKey` from the payload entirely when the default project from integration applies. Omit unused optional fields.

Present results as a table sorted by coverage ascending:

```markdown
## Coverage — `my-project`

Files with lowest coverage (worst first):

| File                | Coverage |
| ------------------- | -------- |
| src/auth/login.py   | 12.5%    |
| src/utils/crypto.py | 23.0%    |
| src/api/routes.py   | 41.8%    |
```

If no files are returned (all files exceed the threshold), say: *"All files meet the coverage threshold."*

Then offer to drill in:
*"Ask me to inspect any of these files for uncovered lines, or invoke the sonar-coverage skill with `--file <file-key>` (add a project key only if needed)."*

**If `mcp__sonarqube__search_files_by_coverage` is unavailable, fall back to `sonar api`.** This needs an explicit project key (no MCP default) — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop.

```bash
sonar api get "/api/measures/component_tree?component=<project-key>&metricKeys=coverage,line_coverage,branch_coverage&qualifiers=FIL&strategy=leaves&s=metric&metricSort=coverage&asc=true[&pullRequest=<id>]"
```

Use `metricKeys`. If a call 400s unexpectedly, add `-v` to see the actual server error. Read `coverage` from each component's `measures` array and present it in the same table format above.

#### Flow B — Line detail (`--file <key>` given, or user asks to inspect a file)

Call `mcp__sonarqube__get_file_coverage_details`:

```json
{
  "key": "<file-key>",
  "pullRequest": "<id>"   // if --pr was given
}
```

The file key format is `<projectKey>:<path>`, e.g. `my-project:src/auth/login.py`.
If the user provides just a path, prepend the resolved project key when you have one; if the integration supplies the default project, the detail tool may accept the path or key format your MCP schema documents — follow the tool schema.

Present uncovered and partially covered lines:

```markdown
## Coverage Detail — `src/auth/login.py`

Overall coverage: **12.5%**

### Uncovered lines
Lines with no test coverage: 14, 15, 23, 45–52, 67

### Partially covered branches
| Line | Covered branches | Total branches |
| ---- | ---------------- | -------------- |
| 30   | 1                | 2              |
| 61   | 0                | 2              |
```

If the file is fully covered, say: *"All lines in this file are covered."*

**If `mcp__sonarqube__get_file_coverage_details` is unavailable, fall back to `sonar api`:**

```bash
sonar api get "/api/sources/lines?key=<file-key>[&pullRequest=<id>]"
```

Each returned line has coverage fields (covered/uncovered, branch hit counts) — derive the uncovered-lines list and partially-covered-branches table from those.

If this also fails, show the standard message above — don't guess further commands.

### Step 4: Next steps

- To write tests for uncovered lines: *"Ask me to add tests for the uncovered lines above."*
- To check for quality issues in the same file: *"Invoke the sonar-list-issues skill with `--component <file>`."*
- To check the quality gate: *"Invoke the sonar-quality-gate skill (add a project key only if you are not using the integration default)."*

View saved version →

---
name: sonar-dependency-risks
description: Search for software composition analysis (SCA) dependency risks in a SonarQube project (project key optional when MCP integration already defines the default project)
argument-hint: "[project-key?] [--branch name] [--pr id]"
allowed-tools: Read, Grep, Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*), Bash(sonar:*)
---

# SonarQube — Dependency Risks

Search for dependency risks (software composition analysis issues) in a SonarQube project, paired with the releases that appear in the analysed project, application, or portfolio.

## Usage

```
sonar-dependency-risks                    # risks in the current project
sonar-dependency-risks my-project         # risks in a specific project
sonar-dependency-risks my-project --branch feature/auth
sonar-dependency-risks my-project --pr 42
```

## Prerequisites

This skill requires SonarQube Advanced Security (available on SonarQube Cloud Enterprise plan, or SonarQube Server 2025.4 Enterprise edition or higher), the SonarQube MCP Server to be configured, and the tool `mcp__sonarqube__search_dependency_risks` to be available in your session.

**Before proceeding**, verify the tool is accessible. If it is not, try the CLI fallback in Step 3 before giving up — don't invent other CLI commands (e.g. `sonar mcp call` or `sonar dependency-risks` do 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. (This only explains missing tools, not the Advanced Security entitlement — see the first cause below.)

- **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 fetch dependency risks.
>
> **Possible causes:**
> - This feature requires SonarQube Advanced Security — available on SonarQube Cloud Enterprise edition, or SonarQube Server 2025.4 Enterprise or higher
> - 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 is wrong or no default project in MCP config — pass an explicit key, or verify `sonar-project.properties` / 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 the project key (only when needed)

MCP tools sometimes **do not require** `projectKey` after the sonar-integrate skill has stored the default project for this workspace. Resolve a key only when you must pass it (tool schema requires it, or the user targets another project):

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **omit `projectKey`** in MCP calls and rely on the integration default.

### Step 2: Parse optional flags from the user-provided arguments

| Flag              | Maps to parameter |
| ----------------- | ----------------- |
| `--branch <name>` | `branchKey`       |
| `--pr <id>`       | `pullRequestKey`  |

### Step 3: Call `mcp__sonarqube__search_dependency_risks`

Include **`projectKey` only if** you resolved one in Step 1 **and** the tool requires it; otherwise omit it.

```json
{
  "projectKey": "<only-if-required>",
  "branchKey": "<name>",       // if --branch was given
  "pullRequestKey": "<id>"     // if --pr was given
}
```

Omit `projectKey` from the payload when the integration default applies. Omit unused optional fields.

**If `mcp__sonarqube__search_dependency_risks` is unavailable, fall back to the CLI.** This needs an explicit project key — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop.

Run `sonar auth status` to check the connected server. On a self-hosted **SonarQube Server**:

```bash
sonar api get "/api/v2/sca/issues-releases?projectKey=<project-key>[&branchKey=<name>][&pullRequestKey=<id>]"
```

On **SonarQube Cloud**, `sonar api` can't reach this endpoint yet (lives on a separate subdomain; may change in a future CLI release) — run a fresh scan instead:

```bash
sonar analyze dependency-risks -p <project-key> --format table
```

This re-scans manifests rather than querying prior results, so it may surface issues not yet on the server dashboard — expected, not an error. Map its output into the same table as Step 4.

If this also fails, show the standard message above — don't guess further commands.

### Step 4: Format the results

**If risks are found**, group by severity and present as a table:

```markdown
## Dependency Risks — `my-project` (branch: `main`)

Found **5 dependency risk(s)**:

### Critical
| Dependency | Version | Risk                  | CVE            |
| ---------- | ------- | --------------------- | -------------- |
| log4j-core | 2.14.1  | Remote code execution | CVE-2021-44228 |

### High
| Dependency       | Version | Risk                          | CVE            |
| ---------------- | ------- | ----------------------------- | -------------- |
| jackson-databind | 2.12.3  | Deserialization vulnerability | CVE-2021-46877 |
| commons-text     | 1.9     | Remote code execution         | CVE-2022-42889 |

### Medium
| Dependency    | Version | Risk              | CVE            |
| ------------- | ------- | ----------------- | -------------- |
| spring-web    | 5.3.18  | DoS vulnerability | CVE-2022-22965 |
| netty-handler | 4.1.68  | SSL/TLS issue     | CVE-2021-43797 |
```

Omit columns that are not present in the response. Omit severity sections that have no risks.

**If no risks are found**:

```markdown
## Dependency Risks — `my-project`

✅ No dependency risks found.
```

### Step 5: Next steps

- To fix a vulnerable dependency: *"Ask me to update `<dependency>` to a safe version."*
- To check the quality gate: *"Invoke the sonar-quality-gate skill (add a project key only if you are not using the integration default)."*
- To check code-level security issues: *"Invoke the sonar-list-issues skill with the project key (or use `sonar.projectKey` in the repo) with filters as needed — `sonar list issues` always requires `-p`."*

View saved version →

---
name: sonar-duplication
description: Find files with code duplications in a SonarQube project and inspect duplication blocks for a file (project key optional when MCP integration already defines the default project)
argument-hint: "[project-key?] [--pr id] [--page-size n] [--page n] [--file key]"
allowed-tools: Read, Grep, Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*), Bash(sonar:*)
---

# SonarQube — Duplication

List files that contain duplicated code in a SonarQube project, then drill into **duplication blocks** for a specific file when needed.

## Usage

```
sonar-duplication                              # all duplicated files in the current project (auto-paginated)
sonar-duplication my-project                   # duplicated files in a specific project
sonar-duplication my-project --pr 42           # same, on a pull request
sonar-duplication my-project --page-size 100 --page 2   # single page of results (manual pagination)
sonar-duplication my-project --file src/auth/login.py   # duplication detail for one file
```

## Prerequisites

This skill requires the SonarQube MCP Server to be configured and the tools `mcp__sonarqube__search_duplicated_files` and `mcp__sonarqube__get_duplications` to be available in your session.

**Before proceeding**, verify the tools are accessible. If they are not, try the `sonar api` CLI fallback in Step 3 before giving up — don't invent other CLI commands (e.g. `sonar mcp call` or `sonar duplication` do not exist).

**If the CLI fallback also fails (for example `sonar` not installed/authenticated, or no project key can be resolved), 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, or project key not found.
>
> **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 is wrong or no default project in MCP config — pass an explicit key, or verify `sonar-project.properties` / 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 the project key (only when needed)

MCP tools sometimes **do not require** `projectKey` after the sonar-integrate skill has stored the default project for this workspace. Resolve a key only when you must pass it (tool schema requires it, or the user targets another project):

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **omit `projectKey`** in MCP calls and rely on the integration default.

### Step 2: Parse optional flags from the user-provided arguments

| Flag              | Meaning                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `--pr <id>`       | Pull request context (maps to `pullRequest`)                                                                 |
| `--page-size <n>` | Results per page for **manual** pagination only; integer 1–500 (maps to `pageSize`)                          |
| `--page <n>`      | Page number for **manual** pagination; starts at **1** (maps to `pageIndex`)                                 |
| `--file <key>`    | Skip the duplicated-files list; fetch duplication blocks for this file (maps to `key` in `get_duplications`) |

**Pagination rule:** By default, call `search_duplicated_files` **without** `pageSize` or `pageIndex` so the MCP server auto-fetches every page of duplicated files (up to **10,000** files). Use `pageSize` and `pageIndex` only when the user asks for a specific page or wants to limit page size. If the user supplies `--page-size` but not `--page`, use `pageIndex` **1**.

### Step 3: Run the appropriate flow

#### Flow A — Duplicated file list (default, no `--file`)

Call `mcp__sonarqube__search_duplicated_files`.

**Default (auto-fetch all pages):**

Include **`projectKey` only if** you resolved one in Step 1 **and** the tool requires it; otherwise omit it.

```json
{
  "projectKey": "<only-if-required>",
  "pullRequest": "<id>"
}
```

Omit `pullRequest` when `--pr` was not given. Omit `pageSize` and `pageIndex` entirely so all duplicated files are retrieved automatically. Omit `projectKey` from the payload when the integration default applies.

**Manual pagination (single page):**

```json
{
  "projectKey": "<only-if-required>",
  "pullRequest": "<id>",
  "pageSize": <n>,
  "pageIndex": <n>
}
```

The tool returns **only files that have duplications**. Present results in a table. Include columns the response provides (for example path, duplicated line counts, or density); sort by the strongest duplication signal if multiple metrics exist (for example highest duplicated-lines density or count first).

```markdown
## Duplication — `my-project`

Files with duplications:

| File                 | Duplicated lines (example) |
| -------------------- | -------------------------- |
| src/auth/login.py    | 42                         |
| src/utils/helpers.py | 18                         |
```

If the list is empty: *"No duplicated files were returned for this project/branch/PR."*

Then offer to drill in:

*"Ask me to open duplications for any file, or invoke the sonar-duplication skill with `--file <file-key>` (add a project key only if needed)."*

**If `mcp__sonarqube__search_duplicated_files` is unavailable, fall back to `sonar api`.** This needs an explicit project key (no MCP default) — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop.

```bash
sonar api get "/api/measures/component_tree?component=<project-key>&metricKeys=duplicated_lines,duplicated_blocks,duplicated_lines_density&qualifiers=FIL&strategy=leaves[&pullRequest=<id>]"
```

Use `metricKeys`; add `-v` if a call 400s unexpectedly. Manual pagination maps to `&p=<page>&ps=<page-size>`; there's no auto-fetch-all mode, so page yourself up to the 10,000-file cap if needed. Filter out components with all-zero duplication metrics, then present the same table as above.

#### Flow B — Duplication detail (`--file <key>` given, or user asks to inspect a file)

Call `mcp__sonarqube__get_duplications`:

```json
{
  "key": "<file-key>",
  "pullRequest": "<id>"
}
```

The file key format is `<projectKey>:<path>`, e.g. `my-project:src/auth/login.py`. If the user provides just a path, prepend the resolved project key when you have one; otherwise follow the MCP tool schema for the default project. Omit `pullRequest` when `--pr` was not given.

> **Permission:** This call requires **Browse** permission on the file’s project. If the tool returns a permission or authorization error, tell the user they need the **Browse** role on the project and that they may need a role with code-view access.

Present duplication **blocks** from the response: for each block, show ranges, sibling copies, or other fields returned by the API so the user can see where code is duplicated.

```markdown
## Duplication detail — `src/auth/login.py`

### Block 1
- Lines 10–24 (example) duplicated in `src/other/helper.py` lines 30–44
...
```

If the file has no duplications in the response, say: *"No duplications were reported for this file."*

**If `mcp__sonarqube__get_duplications` is unavailable, fall back to `sonar api`:**

```bash
sonar api get "/api/duplications/show?key=<file-key>[&pullRequest=<id>]"
```

Omit `pullRequest` when `--pr` was not given. The same **Browse** permission requirement applies. Present the returned blocks in the same format as above.

If this also fails, show the standard message above — don't guess further commands.

### Step 4: Next steps

- To refactor: *"Ask me to extract a shared helper or consolidate the duplicated regions."*
- To scan the same file for issues: *"Invoke the sonar-analyze skill with `<file>`."*
- To check the quality gate (e.g. `new_duplicated_lines_density`): *"Invoke the sonar-quality-gate skill (add a project key only if you are not using the integration default)."*

View saved version →

---
name: sonar-fix-issue
description: Fix a specific SonarQube issue in code by rule key and location
argument-hint: "[rule-key] [file-path:line]"
allowed-tools: Read, Edit, Bash(sonar:*)
---

# SonarQube — Fix Issue

Fix a code quality or security issue identified by SonarQube.

## Usage

```
sonar-fix-issue java:S1481 src/main/java/MyClass.java:42
sonar-fix-issue python:S2077 src/auth/login.py
sonar-fix-issue Remove unused variable in MyClass.java
```

## Instructions

### Step 1: Identify the issue

Parse the user-provided arguments for:
- A rule key (e.g. `java:S1481`, `python:S2077`)
- A file path and optional line number (e.g. `src/auth/login.py:34`)
- Or a plain-language description if no rule key is given

If neither a rule key nor a file path can be determined, ask: *"Which rule and file should I fix?"*

### Step 2: Look up the rule (if a key was given)

Call `mcp__sonarqube__show_rule` with the rule key to retrieve the full rule description,
rationale, and remediation guidance before touching any code. **Do not add extra parameters** (such as `projectKey`) unless the tool schema requires them — after integration, rule lookup usually needs only the rule key.

If the MCP tool is unavailable, fall back to `sonar api get "/api/rules/show?key=<rule-key>"`. If `sonar` is also unavailable or unauthenticated, rely on built-in knowledge of SonarQube rules.

### Step 3: Read the file

Read the full file content. If a line number was given, focus analysis around that line
but read the whole file to understand context.

### Step 4: Apply the fix

- Make the **minimal change** that resolves the rule violation
- Do not refactor surrounding code or fix unrelated issues
- Preserve existing behaviour — the fix must not change what the code does

### Step 5: Explain the change

After editing, briefly explain:
- What the violation was
- Why the rule flags it
- What was changed and why it resolves the issue

### Step 6: Suggest next steps

- *"Invoke the sonar-analyze skill with `<file>` to confirm no new issues were introduced."*
- *"Invoke the sonar-list-issues skill with the project key (or `sonar.projectKey` in `sonar-project.properties`) — the CLI always uses `-p`."*

View saved version →

---
name: sonar-integrate
description: "Installs sonarqube-cli if not already installed, authenticates, and integrates SonarQube with the current agent (installs analysis hooks & SonarQube MCP Server). Use when the user wants to set up SonarQube integration or asks to configure SonarQube."
allowed-tools: Bash(which:*), Bash(Get-Command:*), Bash(sonar:*), Bash(agy:*), Bash(curl:*), Bash(irm:*), Bash(iex:*), Bash(brew:*), Bash(mise:*), Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*)
---

# Integrate SonarQube

Guide the user through installing **sonarqube-cli** (if needed), **updating it to the latest version** when already installed, authenticating, and completing agent-specific integration. Assume SonarQube itself is already set up; this skill only wires the assistant.

## Instructions

Interaction rule: for every finite decision, always present predefined selector options (single-choice or multi-choice as appropriate) instead of asking for free-form text. If the user gives an invalid answer, re-show the same selector.

### Step 1 — Check for sonarqube-cli and update it

Check if `sonar` is available on the PATH by running `which sonar` (macOS/Linux) or `Get-Command sonar` (Windows) yourself.

**If found:** first determine how it was installed, because the upgrade path differs:

- **Managed by a package or version manager** (e.g. installed via Homebrew or mise — the binary lives under the manager's prefix rather than `~/.local/share/sonarqube-cli/bin`): do **not** run `sonar self-update`, as it conflicts with the manager. Run the manager's upgrade command yourself instead (Homebrew: `brew upgrade --cask sonarqube-cli`; mise: `mise upgrade aqua:SonarSource/sonarqube-cli`), then go to Step 2. If the upgrade fails, show the output but **still continue** to Step 2 as long as `sonar` remains usable.
- **Installed via the shell/PowerShell script, or unsure:** run **`sonar self-update`** yourself and wait for it to finish.
  - **If it succeeds:** briefly tell the user the CLI is up to date (or was upgraded), then go to Step 2.
  - **If it fails:** show the relevant output, suggest they run `sonar self-update` manually (e.g. offline or network issues), then **still continue** to Step 2 if `sonar` remains usable — do not block the rest of the flow unless the binary is missing or broken.

**If not found:** pick an install command from the table below, show it to the user, and ask for explicit confirmation **before running it**. Do **not** execute the command until the user confirms.

The shell/PowerShell script is the default and works everywhere. If the user already manages CLIs with **Homebrew** or **mise**, prefer that route so future upgrades stay managed by the tool — the Step 1 update above then defers to the manager.

| Platform / method        | Install command                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| macOS / Linux (script)   | `curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh \| bash` |
| macOS / Linux (Homebrew) | `brew install --cask sonarqube-cli`                                                                                      |
| Any OS (mise)            | `mise use -g aqua:SonarSource/sonarqube-cli`                                                                             |
| Windows (PowerShell)     | `irm https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.ps1 \| iex`      |

**If the user confirms:** run the command yourself using a shell command. After it finishes, re-run the PATH check (`which sonar` or `Get-Command sonar`) yourself to verify before continuing.

**If the user declines:** stop the skill and ask the user to install `sonarqube-cli` manually and then re-invoke the sonar-integrate skill.

---

### Step 2 — Check authentication status

Run `sonar auth status` yourself using a shell command.

**If already authenticated:** note the connected server and organisation from the output,
then skip directly to Step 4.

**If not authenticated:** proceed to Step 3.

---

### Step 3 — Authenticate (`sonar auth login`)

This step requires user interaction — do **not** run it yourself.

First determine the connection type using a single-choice selector with these options:

1. SonarQube Cloud - EU (default)
2. SonarQube Cloud - US
3. Self-hosted SonarQube Server

Do not ask an open-ended text question for this decision.

Collect:

| Scenario                       | Information needed                                            |
| ------------------------------ | ------------------------------------------------------------- |
| SonarQube Cloud — EU (default) | organization key (e.g. `my-org`)                              |
| SonarQube Cloud — US           | organization key + confirm US region (`https://sonarqube.us`) |
| SonarQube Server               | server URL (e.g. `https://sonarqube.yourcompany.com`)         |

Build the login command and show it to the user:

| Scenario             | Command                                                 |
| -------------------- | ------------------------------------------------------- |
| SonarQube Cloud — EU | `sonar auth login -o <org-key>`                         |
| SonarQube Cloud — US | `sonar auth login -o <org-key> -s https://sonarqube.us` |
| SonarQube Server     | `sonar auth login -s <server-url>`                      |

Tell the user:

> "Run the command below — it will open your browser to log in. The token is stored
> securely in your system keychain and never appears in this chat."

Wait for the user to confirm they logged in, then run `sonar auth status` yourself to
verify before continuing.

---

### Step 4 — Agent-specific integration

> **Container runtime requirement:** The SonarQube MCP Server runs inside a container, started via `sonar run mcp` (which detects Docker, Podman, or Nerdctl). A container runtime must be **installed and running** for the MCP tools to load — otherwise integration can complete successfully yet no `mcp__sonarqube__*` tools appear in the session. **Verify this yourself:** run `docker ps` (falling back to `podman ps` / `nerdctl ps`). If one succeeds, the runtime is up — proceed. If none do, tell the user their container runtime is not running and ask them to start it, then note they must restart the agent session afterward for the tools to load (starting the daemon and restarting the session are the only parts you cannot do for them).

Pick exactly one branch below based on which agent you are. Do not run the other branches.

- Claude Code -> **4.a**
- Copilot CLI -> **4.b**
- Codex -> **4.c**
- Cursor -> **4.d**
- Antigravity -> **4.e**
- Gemini CLI -> **4.f**

#### 4.a — Claude Code (`sonar integrate claude`)

Run **`sonar integrate claude`**, which configures the **SonarQube MCP Server**, **secrets-scanning hooks**, and any other supported integration the CLI applies.

It wires **MCP** (for skills like sonar-quality-gate, sonar-analyze, sonar-coverage, sonar-duplication, sonar-dependency-risks) and **secrets-scanning hooks** into the user’s Claude Code config. When available, SonarQube Vortex analysis hooks are also installed.

Ask the user using a single-choice selector with these options:

1. Current project only (default)
2. Global (all projects)

Do not ask an open-ended text question for this decision.

Then run the appropriate command yourself using a shell command, and adding `--non-interactive`:

| Scenario     | Command                                             |
| ------------ | --------------------------------------------------- |
| Project-only | `sonar integrate claude --non-interactive`          |
| Global       | `sonar integrate claude --global --non-interactive` |

#### 4.b — Copilot CLI (`sonar integrate copilot`)

Run **`sonar integrate copilot`**, which configures the **SonarQube MCP Server**, **secrets-scanning hooks**, and any other supported integration the CLI applies.

It wires **MCP** (for skills like sonar-quality-gate, sonar-analyze, sonar-coverage, sonar-duplication, sonar-dependency-risks) and **secrets-scanning hooks** into the user’s Copilot CLI config.

Ask the user using a single-choice selector with these options:

1. Current project only (default)
2. Global (all projects)

Do not ask an open-ended text question for this decision.

Then run the appropriate command yourself using a shell command, and adding `--non-interactive`:

| Scenario     | Command                                             |
| ------------ | --------------------------------------------------- |
| Project-only | `sonar integrate copilot --non-interactive`          |
| Global       | `sonar integrate copilot --global --non-interactive` |

#### 4.c — Codex (`sonar integrate codex`)

Run **`sonar integrate codex`**, which configures the **SonarQube MCP Server**, **secrets-scanning hooks**, and—when your SonarQube Cloud org has Vortex analysis—a **PostToolUse** hook on **`apply_patch`** that surfaces findings inline after edits.

Ask the user using a single-choice selector with these options:

1. Current project only (default)
2. Global (all projects)

Do not ask an open-ended text question for this decision.

Then run the appropriate command yourself using a shell command, and adding `--non-interactive`:

| Scenario     | Command                                            |
| ------------ | -------------------------------------------------- |
| Project-only | `sonar integrate codex --non-interactive`          |
| Global       | `sonar integrate codex --global --non-interactive` |

If the project key is not already known from `sonar-project.properties` or prior context, add **`--project <key>`** to the project-only command.

#### 4.d — Cursor (`sonar integrate cursor`)

Run **`sonar integrate cursor`**, which configures **secrets-scanning hooks** (`beforeSubmitPrompt`, `beforeReadFile`, and `preToolUse`), **MCP**, **Context Augmentation** (when entitled), and **Vortex analysis instructions** (when entitled, project scope only).

Ask the user using a single-choice selector with these options:

1. Current project only (default)
2. Global (all projects)

Do not ask an open-ended text question for this decision.

Then run the appropriate command yourself using a shell command, adding **`--non-interactive`**:

| Scenario     | Command                                                |
| ------------ | ------------------------------------------------------ |
| Project-only | `sonar integrate cursor --non-interactive`             |
| Global       | `sonar integrate cursor --global --non-interactive`    |

If the project key is not already known from `sonar-project.properties` or prior context, add **`--project <key>`** to the project-only command.

After integrate completes, tell the user to enable the MCP server manually in Cursor: open **Settings → MCP**, find the `sonarqube` entry, and toggle it on. Also tell the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running. A Cursor session restart may be needed for the tools to appear.

#### 4.e — Antigravity (`sonar integrate antigravity`)

Run **`sonar integrate antigravity`**, which configures **secrets-scanning hooks**, **prompt-secrets and Vortex analysis instructions**, **Context Augmentation** (when entitled), and **MCP** in the Antigravity harness.

Ask the user using a single-choice selector with these options:

1. Current project only (default)
2. Global (all projects)

Do not ask an open-ended text question for this decision.

Then run the appropriate command yourself using a shell command, adding **`--non-interactive`**:

| Scenario     | Command                                                |
| ------------ | ------------------------------------------------------ |
| Project-only | `sonar integrate antigravity --non-interactive`        |
| Global       | `sonar integrate antigravity --global --non-interactive` |

If the project key is not already known from `sonar-project.properties` or prior context, add **`--project <key>`** to the project-only command.

Tell the user to ensure a container runtime (Docker, Podman, or Nerdctl) is running, and to restart the Antigravity session if MCP tools do not appear after integrate completes.

#### 4.f — Gemini CLI *(legacy)*

Gemini CLI starts the SonarQube MCP Server via `sonar run mcp`, which handles container runtime detection (Docker, Podman, Nerdctl) and authentication automatically. Authentication was handled in Steps 2–3.

Confirm that integration is ready — the MCP server will start automatically when Gemini CLI reads **`gemini-extension.json`**.

Recommend migrating to **Antigravity** (**4.e**): run **`agy plugin import gemini`**, then **`sonar integrate antigravity`**. Gemini CLI did not support SonarQube hooks or Vortex analysis wiring.

---

### Summary message

After all steps complete, print a summary:

```
✅ SonarQube integration is ready.

  sonarqube-cli:     up to date
  Authentication:    token stored in system keychain
  MCP Server:        configured (ensure a container runtime (Docker, Podman, or Nerdctl) is running, then restart the agent session if tools do not appear)

You can verify at any time with:  sonar auth status
To refresh CLI + wiring later:    invoke the sonar-integrate skill again
```

If path **4.a** (Claude Code) was taken, add this line to the summary:

```
  Secrets scanning:  hooks registered via sonar integrate claude
```

If path **4.b** (Copilot CLI) was taken, add this line to the summary:

```
  Secrets scanning:  hooks registered via sonar integrate copilot
```

If path **4.c** (Codex) was taken, add this line to the summary:

```
  Hooks & MCP:       wired via sonar integrate codex
```

If path **4.d** (Cursor) was taken, add these lines to the summary:

```
  CLI integrate:     wired via sonar integrate cursor
  MCP Server:        enable manually in Cursor Settings → MCP (ensure a container runtime (Docker, Podman, or Nerdctl) is running; restart may be needed)
```

And **omit** the default `MCP Server` line (it is replaced by the Cursor-specific one above).

If path **4.e** (Antigravity) was taken, add these lines to the summary:

```
  CLI integrate:     wired via sonar integrate antigravity
```

If path **4.f** (Gemini CLI) was taken, no extra line is required beyond the default MCP summary.

If **sonarqube-cli was freshly installed** in Step 1, replace the `sonarqube-cli` summary line with `sonarqube-cli: installed`.

If **`sonar self-update`** failed in Step 1, adjust the summary: omit the `sonarqube-cli` line or state that the CLI was not updated and suggest `sonar self-update` in a terminal.

If any other step failed, note it clearly and suggest the corrective action.

View saved version →

---
name: sonar-list-issues
description: Search and filter SonarQube issues for a project, branch, or pull request via sonarqube-cli (`-p` is always required on the CLI; resolve the key from user arguments or sonar-project.properties)
argument-hint: "[project-key?] [--severities values] [--statuses values] [--branch name]"
allowed-tools: Read, Grep, Bash(sonar:*)
---

# SonarQube — List Issues

Search for issues in a SonarQube project using the `sonarqube-cli`.

Unlike SonarQube MCP tools (which may use a default project from integration), **`sonar list issues` always requires `-p <project-key>`**. Resolve the key from the user-provided arguments or `sonar-project.properties` before running the CLI.

## Usage

```
sonar-list-issues                                          # issues in the current project
sonar-list-issues my-project                               # issues in a specific project key
sonar-list-issues my-project --severities CRITICAL,BLOCKER # filter by severities
sonar-list-issues my-project --statuses OPEN,CONFIRMED     # filter by status
sonar-list-issues my-project --branch main                 # on a specific branch
sonar-list-issues my-project --pr 42                       # on a pull request
```

## Prerequisites

This skill uses the `sonarqube-cli` command. The CLI must be installed and authenticated before proceeding.

**Before proceeding**, verify that `sonar` is available on your PATH and authenticated. If it is not, do not attempt to call any alternative commands or invent alternatives, and show the user:

> Unable to list issues.
>
> **Possible causes:**
> - `sonarqube-cli` not installed or not authenticated — invoke the sonar-integrate skill
> - Project key is wrong or missing — `-p` is mandatory for `sonar list issues`; invoke the sonar-list-projects skill or set `sonar.projectKey` in `sonar-project.properties`

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 re-check and continue; if they decline, stop.

## Instructions

### Step 1: Resolve the project key

This flow uses **`sonar list issues`** (CLI), not MCP. The CLI **always** needs **`-p <project-key>`** — do not invoke it without a resolved key.

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **do not run** `sonar list issues`. Tell the user: *"Invoke the sonar-list-projects skill to find your project key, then re-run with that key,"* or add `sonar.projectKey` to `sonar-project.properties`. (MCP integration defaults do **not** apply to this CLI command.)

### Step 2: Parse optional flags from the user-provided arguments

| Flag                     | Maps to CLI option |
| ------------------------ | ------------------ |
| `--severities <values>`  | `--severities`     |
| `--statuses <values>`    | `--statuses`       |
| `--branch <name>`        | `--branch`         |
| `--pr <id>`              | `--pull-request`   |

> `sonar list issues` does **not** support filtering by issue type, rule, tag, or component, nor a `--resolved` flag. Only the options above (plus `--format`, `--page`, and `--page-size`) exist. To filter by rule/type/tag/component or to drill into a single file, use the MCP-based skills (e.g. sonar-analyze for a file, or `mcp__sonarqube__search_sonar_issues_in_projects`).

### Step 3: Validate arguments

Before building the command, validate each user-supplied value against the following rules. If any value fails validation, stop and tell the user what was rejected and why — do not run the command. Validate the resolved project key (from args or `sonar-project.properties`) against the project-key pattern before running the CLI.

| Argument       | Allowed pattern                                                                       |
| -------------- | ------------------------------------------------------------------------------------- |
| project key    | `^[a-zA-Z0-9_\-\.:]+$`                                                                |
| `--severities` | comma-separated subset of: `INFO`, `MINOR`, `MAJOR`, `CRITICAL`, `BLOCKER`, `HIGH`, `MEDIUM`, `LOW` |
| `--statuses`   | comma-separated subset of: `OPEN`, `CONFIRMED`, `FALSE_POSITIVE`, `ACCEPTED`, `FIXED` |
| `--branch`     | `^[a-zA-Z0-9_\-\./]+$`                                                                |
| `--pr`         | digits only                                                                           |

### Step 4: Run `sonar list issues`

Build and run the command using a shell command. **Always** pass **`-p`** with the key resolved in Step 1.

```bash
sonar list issues -p <project-key> --format toon [--severities <values>] [--statuses <values>] [--branch <name>] [--pull-request <id>]
```

Only include optional flags that were provided.

### Step 5: Format the results

**If issues are found**, present a summary line then a table sorted by severity then line number:

```markdown
## SonarQube Issues — `my-project` (branch: `main`)

Found **12 issue(s)**:

| File                 | Line | Severity  | Rule         | Message                       |
| -------------------- | ---- | --------- | ------------ | ----------------------------- |
| src/auth/login.py    | 12   | 🔴 Blocker | python:S2077 | SQL injection risk            |
| src/utils/helpers.py | 34   | 🟠 High    | python:S2259 | Null dereference              |
| src/api/routes.py    | 67   | 🟡 Medium  | python:S3776 | Cognitive complexity too high |
```

Severity icons (the label depends on the server version):
- 🔴 Blocker
- 🟠 Critical / High
- 🟡 Major / Medium
- 🔵 Minor / Low
- ⚪ Info

**If no issues are found**:

```markdown
## SonarQube Issues — `my-project`

✅ No issues found.
```

### Step 6: Next steps

- To fix a specific issue: *"Ask me to fix `<rule>` at `<file>:<line>`."*
- To check the quality gate: *"Invoke the sonar-quality-gate skill."*

View saved version →

---
name: sonar-list-projects
description: List SonarQube projects accessible to the current user
argument-hint: "[search-query]"
allowed-tools: Bash(sonar:*)
---

# SonarQube — List Projects

List SonarQube projects accessible to the authenticated user. Useful for discovering project keys before running other skills.

## Usage

```
sonar-list-projects                      # list all accessible projects
sonar-list-projects my-project              # search by name or key
```

## Prerequisites

This skill uses the `sonarqube-cli` command. The CLI must be installed and authenticated before proceeding.

**Before proceeding**, verify that `sonar` is available on your PATH and authenticated. If it is not, do not attempt to call any alternative commands or invent alternatives, and show the user:

> Unable to list projects.
>
> **Possible causes:**
> - `sonarqube-cli` not installed or not authenticated — invoke the sonar-integrate skill

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 re-check and continue; if they decline, stop.

## Instructions

### Step 1: Parse optional search term from the user-provided arguments

- If the user provided a search term (not a flag), pass it as `--query`.

### Step 2: Validate arguments

If a `--query` search term was provided, validate it matches `^[a-zA-Z0-9_\-\. ]+$`. If it does not, stop and tell the user what was rejected — do not run the command.

### Step 3: Run `sonar list projects`

Build and run the command using a shell command:

```bash
sonar list projects [--query <search-term>]
```

Only include `--query` if a search term was provided.

### Step 4: Format the results

**If projects are found**:

```markdown
## SonarQube Projects

Found **8 project(s)**:

| Project key       | Name            |
| ----------------- | --------------- |
| my-org_backend    | Backend Service |
| my-org_frontend   | Frontend App    |
| my-org_shared-lib | Shared Library  |
```

**If no projects are found**:

```markdown
## SonarQube Projects

No projects found. If you expected results, check your authentication with `sonar auth status`.
```

**If the result is paginated** (500 projects returned), note: *"Showing first 500 projects. Use a search term to narrow results."*

### Step 5: Next steps

- To list issues: *"Invoke the sonar-list-issues skill with the project key, or ensure `sonar.projectKey` is in `sonar-project.properties` — the CLI always requires `-p`."*
- To check the quality gate: *"Invoke the sonar-quality-gate skill — add a project key only if you are not using the MCP integration default."*

View saved version →

---
name: sonar-quality-gate
description: Show SonarQube quality gate status for a project — pass/fail and each condition (metric key, threshold, actual value), plus worst-offender breakdowns. Project key optional — resolved from `sonar-project.properties` or the MCP integration default.
argument-hint: "[project-key?] [--branch name] [--pr id]"
allowed-tools: Read, Grep, Bash(docker ps:*), Bash(podman ps:*), Bash(nerdctl ps:*), Bash(sonar:*)
---

# SonarQube — Quality gate

Report **only** the quality gate evaluation for a SonarQube project: overall status, every **condition** returned by the API, and worst-offender breakdowns for failing conditions. Do not pull a broad measures dashboard here — for numeric metrics beyond the gate (coverage %, issue counts, ratings as measures, and so on), use **`mcp__sonarqube__get_component_measures`** afterward with the `metricKeys` you care about.

## Usage

```
sonar-quality-gate                       # quality gate for the current project
sonar-quality-gate my-project            # quality gate for a specific project key
sonar-quality-gate my-project --branch release/2.0
sonar-quality-gate my-project --pr 42
```

## Prerequisites

This skill uses the `sonarqube-cli` command **`sonar quality-gate status`** (alias `sonar qg status`) as the primary path — don't invent other ones (e.g. `sonar mcp call` does not exist). Prefer it over the MCP tool: the CLI returns worst-offender breakdowns per failing condition in the same call — see Step 5 — while the MCP tool needs separate follow-up calls (measures, issues) for that detail.

**Before proceeding**, verify `sonar` is available on your PATH and authenticated. If it is **not installed or not authenticated**, the MCP fallback cannot help either — the SonarQube MCP Server is itself started via `sonar run mcp` and shares the CLI's stored credentials (true whenever it was set up through the sonar-integrate skill; doesn't apply if the `sonarqube` MCP server was configured independently, e.g. via a standalone Docker container with its own token) — so skip straight to the message below and recommend the sonar-integrate skill. Only when `sonar` works but `quality-gate status` itself is unavailable (unknown subcommand on an older CLI, or the command errors for another reason) fall back to the MCP tool `mcp__sonarqube__get_project_quality_gate_status` in Step 3.

**If the MCP fallback also fails (for example the tool is unavailable, or no project key can be resolved), 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 run `sonar quality-gate status`, reach the SonarQube MCP Server, or resolve a project key.
>
> **Possible causes:**
> - `sonarqube-cli` not installed or not authenticated — invoke the sonar-integrate skill
> - 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 is wrong or no default project in MCP config — pass an explicit key, or verify `sonar-project.properties` / 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 the project key (only when needed)

`sonar quality-gate status` does **not require** `-p` — unlike `sonar list issues` (where it's mandatory), it resolves the project from `sonar.projectKey` in `sonar-project.properties` when `-p` is absent. Resolve a key only when you must pass it (the user targets another project, or you fall back to the MCP tool in Step 3 and its schema requires it):

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **omit `-p`** on the CLI and let it auto-resolve. For the MCP fallback, **omit `projectKey`** and rely on the integration default instead.

### Step 2: Parse optional filters from the user-provided arguments

| Flag              | CLI option       | MCP parameter (fallback) |
| ----------------- | ---------------- | ------------------------- |
| `--branch <name>` | `--branch`       | `branchKey`                |
| `--pr <id>`        | `--pull-request` | `pullRequestKey`            |

`--branch` and `--pr` are mutually exclusive — if the user passes both, stop and ask which one they mean. Omit flags/keys not provided. If the MCP tool uses different parameter names, follow the schema exposed by your SonarQube MCP server.

### Step 3: Run `sonar quality-gate status`

Before running the command, validate the values you are about to interpolate — project key against `^[a-zA-Z0-9_\-\.:]+$`, `--branch` against `^[a-zA-Z0-9_\-\./]+$`, `--pull-request` digits only (same rules as the sonar-list-issues skill). If any value fails, stop and tell the user what was rejected instead of running the command.

```bash
sonar quality-gate status [-p <project-key>] [--branch <name> | --pull-request <id>] --format json
```

Always use `--format json` and parse it — don't relay the CLI's default `table` output straight to the user; route the parsed result through Step 4's formatting.

The command returns a top-level **`status`** (`OK`, `ERROR`, or other values your server uses) and a **`conditions`** array. Each condition typically includes:

| Field            | Meaning                                                                 |
| ---------------- | ----------------------------------------------------------------------- |
| `metricKey`      | SonarQube metric identifier for the gate condition                      |
| `status`         | Per-condition result (`OK`, `ERROR`, …)                                 |
| `errorThreshold` | Required bound when the gate defines one (may be absent for some types) |
| `actualValue`    | Value SonarQube compared against the threshold                          |

On a CLI new enough to support it, the same call also returns a **`breakdown`** on each failing condition — see Step 5, don't fetch it separately; if `breakdown` is absent, treat that as "not available", not an error.

**Example (all conditions OK)** — response shape:

```json
{
  "status": "OK",
  "conditions": [
    {
      "metricKey": "reliability_rating",
      "status": "OK",
      "errorThreshold": "2",
      "actualValue": "1"
    },
    {
      "metricKey": "security_rating",
      "status": "OK",
      "errorThreshold": "1",
      "actualValue": "1"
    },
    {
      "metricKey": "new_duplicated_lines_density",
      "status": "OK",
      "errorThreshold": "3",
      "actualValue": "0.0"
    }
  ]
}
```

**Example (failing gate)** — note missing `errorThreshold` on some conditions is normal:

```json
{
  "status": "ERROR",
  "conditions": [
    {
      "metricKey": "new_coverage",
      "status": "ERROR",
      "errorThreshold": "85",
      "actualValue": "82.50562381034781"
    },
    {
      "metricKey": "new_blocker_violations",
      "status": "ERROR",
      "errorThreshold": "0",
      "actualValue": "14"
    },
    {
      "metricKey": "new_sqale_debt_ratio",
      "status": "OK",
      "errorThreshold": "5",
      "actualValue": "0.6562109862671661"
    },
    {
      "metricKey": "reopened_issues",
      "status": "OK",
      "actualValue": "0"
    },
    {
      "metricKey": "open_issues",
      "status": "ERROR",
      "actualValue": "17"
    }
  ]
}
```

**If `sonar quality-gate status` itself is unavailable (unknown subcommand on an older CLI, or the command fails for a reason other than a missing/unauthenticated CLI), fall back to `mcp__sonarqube__get_project_quality_gate_status`.** If `sonar` is not installed or not authenticated, don't try the MCP tool — the MCP server runs via `sonar run mcp` and shares the CLI's credentials, so it will be unavailable too — unless the `sonarqube` MCP server was configured independently (e.g. via a standalone Docker container with its own token), in which case the MCP tool may still work, so try it; show the message in Prerequisites and recommend sonar-integrate instead. Include **`projectKey` only if** you resolved one in Step 1 **and** the tool requires it; otherwise omit it and rely on the integration default. Example payload:

```json
{
  "projectKey": "<only-if-required>",
  "branchKey": "<name, if --branch was given>",
  "pullRequestKey": "<id, if --pr was given instead>"
}
```

Include `branchKey` only when `--branch` was given, and `pullRequestKey` only when `--pr` was given — never both (see Step 2). Omit `projectKey` from the payload when the integration default applies. Omit unused keys.

The tool returns the same `status`/`conditions` shape as above, but with **no `breakdown`** — see Step 5.

### Step 4: Format the results

Present a concise report:

1. **Headline** — Map top-level `status` to plain language (e.g. `OK` → passed, `ERROR` → failed). Include project key and branch/PR context if known.
2. **Conditions table** — One row per element of `conditions`, columns at minimum:
   - **Metric** — `metricKey` (humanize lightly if you know the name; otherwise keep the key).
   - **Condition status** — `status`.
   - **Threshold** — `errorThreshold` when present; use `—` when absent.
   - **Actual** — `actualValue` when present; use `—` when absent.

Sort so failing conditions (`ERROR` or non-OK, per server rules) appear **before** passing ones.

3. **Ratings** — For keys like `reliability_rating` / `security_rating`, SonarQube often encodes ratings as numeric grades in the API (for example 1 = A, 5 = E). Mention that interpretation when it helps the user.

4. **No extra measures** — Do not call `get_component_measures` inside this skill unless the user explicitly asks for deeper metrics in the same turn. When they need more detail, tell them the next step (see Step 6).
5. **Breakdown (CLI path only)** — When a condition carries a `breakdown` (Step 3's primary CLI path, new enough CLI version), render it as a short indented list under that condition's row using the fields relevant to its category (see Step 5 for the shape per category). Skip this entirely when `breakdown` is absent or you're on the MCP fallback.

If the quality gate payload is missing or analysis has not run, say so clearly instead of inventing values.

### Step 5: Treat failing conditions by category

A failing gate is rarely one flat list — treat each failing condition according to the kind of metric it is. On the **primary CLI path**, this is close to free: `sonar quality-gate status` already groups every failing condition's worst offenders into a `breakdown` (or, on an older CLI without this enrichment yet, no `breakdown` field at all — treat that the same as "not available", not an error). On the **MCP fallback**, the tool gives you `conditions` only, with no breakdown — use the metric key to categorize below, then hand off to the matching skill for detail.

Example `breakdown` on a failing coverage condition (CLI path):

```json
{
  "metricKey": "new_coverage",
  "status": "ERROR",
  "errorThreshold": "85",
  "actualValue": "82.5",
  "breakdown": [
    { "file": "src/auth/login.py", "coverage": "42.0" },
    { "file": "src/utils/helpers.py", "coverage": "58.3" }
  ]
}
```

Group by metric key:

- **Coverage** (`coverage`, `new_coverage`, `branch_coverage`, `line_coverage`, …) — the breakdown lists the worst files by coverage %. Tell the user which files most need tests. For line-level detail on a specific file, hand off to **sonar-coverage**.
- **Duplications** (`duplicated_lines_density`, `new_duplicated_lines_density`, `duplicated_blocks`, …) — the breakdown lists the worst files, each with its duplicate block count and the peer files it duplicates. Suggest extracting a shared helper. For the full duplication blocks, hand off to **sonar-duplication**.
- **Issues & Security** (`violations`, `bugs`, `code_smells`, `reliability_rating`, `sqale_rating`/`new_maintainability_rating`, and — on a CLI new enough to support it — `vulnerabilities`/`security_rating`) — the breakdown is already the actual failing issues (file, line, key, rule, message), usually enough to act on directly. For broader filtering (severities, statuses, other files), hand off to **sonar-list-issues**.
- **Dependency risks** (metric keys starting with `sca_`, e.g. `sca_count_*`, `sca_rating_*`, `sca_severity_*`) — the breakdown is a flat package/version/severity/type list with **no file location**: SCA risks are project-level, not tied to a specific file or line. It reflects unresolved risks already known to the server. For a fresh re-scan of manifests or CVE-level detail, hand off to **sonar-dependency-risks**.

If you're on the **primary CLI path** and need to focus on just one category (for example the user asks specifically "why did coverage fail?"), re-run `sonar quality-gate status` with `--category <coverage|duplications|issues|dependency-risks>` (values match the metric groups above; support depends on your CLI version); `--top <n>` controls how many entries each breakdown includes. Leaving `--category` off, as in Step 3, already returns breakdowns for every category at once — only narrow it down on request. On the **MCP fallback** there is no CLI call to re-run: hand off to the matching skill above instead.

### Step 6: Deeper metrics (`get_component_measures`)

To investigate **beyond** the gate (e.g. overall coverage, line coverage, bug counts, detailed ratings), call **`mcp__sonarqube__get_component_measures`** with the same branch/PR context if applicable, and pass `metricKeys` for the measures you need. Add **`projectKey` only when** the tool requires it and you have a resolved key; otherwise rely on the integration default (you can start from the `metricKey` values that failed or from the [SonarQube metric keys](https://docs.sonarsource.com/) documentation).

**If the tool is unavailable, fall back to `sonar api`** (this one *does* require a resolved project key — unlike `sonar quality-gate status` in Step 3, which auto-resolves from `sonar-project.properties` — if none was resolved in Step 1, ask the user or invoke sonar-list-projects, then stop):

```bash
sonar api get "/api/measures/component?component=<project-key>&metricKeys=<comma-separated-keys>[&branch=<name>][&pullRequest=<id>]"
```

If this also fails, show the standard message above — don't guess further commands.

### Step 7: Related skills

Only needed for detail beyond what Step 5's breakdown already gave you:

- **sonar-list-issues** — filter issues/security findings by severity, status, or beyond the top entries already shown.
- **sonar-coverage** — line-by-line coverage detail for a specific file.
- **sonar-duplication** — full duplication blocks for a specific file.
- **sonar-dependency-risks** — a fresh dependency-risk scan or deeper CVE detail.