npm package: @php-workx/skill-sonarqube
Description: SonarQube/SonarCloud skill for AI coding agents (Claude, Codex, Cursor). Scan changed files, list findings by severity, or autofix issues autonomously.
Latest version: 1.3.2

# skill-sonarqube

SonarQube/SonarCloud skill package for Codex and Claude.

This repository provides:

- `sonarqube` skill definitions for Codex and Claude
- `/sonarqube` prompt command for Codex
- installer script to copy skill files into user skill directories

## Features

- Scan only files changed on the current branch (vs base ref)
- Local mode auto-starts SonarQube, creates the project, configures the new code period, and persists a generated token in repo-local `.env`
- Two actions:
  - `list`: aggregated findings by severity
  - `autofix`: iteratively fix findings at/above threshold
- Two scan modes:
  - `local`: local SonarQube instance/container
  - `cloud`: SonarCloud/SonarQube cloud APIs or MCP
- Reads `sonar-project.properties` for `sonar.projectKey`, `sonar.host.url`, `sonar.sources`, and `sonar.tests`
- Warns when test paths are mixed into `sonar.sources` without `sonar.tests`
- Generates a Rust clippy report automatically when `Cargo.toml` is present
- Supports both severity models (`high/medium/...` and `critical/major/...`)

## Prerequisites

- `python3`
- `sonar-scanner` (local mode only)
- `docker` (local mode only, for SonarQube container workflows)

Cloud mode only requires `python3`, `git`, and a `SONAR_TOKEN`.

## Install

### Via OpenSkills

```bash
# project-local install
npx openskills install php-workx/skill-sonarqube

# global install
npx openskills install -g php-workx/skill-sonarqube
```

### Via skills.sh

```bash
# project-local install
npx skills add php-workx/skill-sonarqube

# global install
npx skills add -g php-workx/skill-sonarqube
```

### Via npm (public npmjs)

```bash
npm install @php-workx/skill-sonarqube
```

The npmjs package is published from GitHub Actions using npm trusted publishing, so CI does not require a long-lived npm publish token.

### Via npm (GitHub Packages)

```bash
npm install @php-workx/skill-sonarqube --registry=https://npm.pkg.github.com
```

### Via installer script

```bash
git clone --depth 1 --branch v1.3.0 https://github.com/php-workx/skill-sonarqube.git
cd skill-sonarqube
bash scripts/install-sonarqube-skill.sh
```

After install, restart Codex/Claude so new skills and slash commands are loaded.

## Usage

Codex slash command:

```text
/sonarqube list
/sonarqube autofix local high
/sonarqube autofix cloud medium
```

Natural language usage also works when `sonarqube` skill is selected by intent.

## Configuration

Runtime environment variables:

- `SONAR_TOKEN` (preferred; falls back to repo-local `.env` in local mode)
- `SONAR_USER`, `SONAR_PASSWORD` (fallback)
- `SONAR_HOST_URL` (default `http://localhost:9000`)

Local mode also reads `sonar-project.properties` directly before falling back to `.sonarqube-skill.yaml` for host and source settings.

Installer destination overrides:

- `CLAUDE_SKILLS_DIR`
- `CODEX_SKILLS_DIR`
- `CODEX_PROMPTS_DIR`

See `docs/CONFIGURATION.md` for details.

## Python Tooling

Repo-local Python tooling uses `uv` for optional development helpers such as `skill-creator` validation:

```bash
uv sync --dev
npm run validate:skill
```

If the `skill-creator` validator lives outside the default install locations, set `SKILL_CREATOR_VALIDATE_SCRIPT` to its `quick_validate.py` path before running `npm run validate:skill`.

## Repository Layout

- `skills/sonarqube/` — canonical skill source for indexers and installers (SKILL.md, scripts, agents config)
- `prompts/sonarqube.md` — Codex slash command dispatcher
- `scripts/install-sonarqube-skill.sh` — copies skill to both Claude and Codex directories

## Troubleshooting

See `docs/TROUBLESHOOTING.md`.

## Release Process

See `docs/RELEASE.md`.