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

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

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

Via skills.sh

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

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

Via npm (public npmjs)

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)

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

Via installer script

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:

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

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.