From d5ca10b2a9b5020e0079fe52572654784c423575 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 12:40:18 +0100 Subject: [PATCH 1/7] docs: add Codacy Skills section under Developer tools Codacy Skills was documented only as a section of the Codacy Cloud CLI page, which named one of the six skills that ship in codacy/codacy-skills. The other five were absent from the site, and setup-coverage was covered by an outbound link to a SKILL.md on GitHub. Add docs/codacy-skills/index.md as its own section in the Developer tools tab, listing every skill, which CLI it needs, and how to install the set on Claude Code, Claude.ai, Codex, Copilot, and Gemini CLI. The Cloud CLI page keeps its #install-the-codacy-skills anchor, reduced to a pointer, so inbound links from the product UI, blog, and support macros still resolve. Pages that linked to that anchor now link to the new page. Vendor document-text-outline for the sidebar, converted to explicit fill/stroke attributes since the theme does not ship the Ionicons CSS. Co-Authored-By: Claude Opus 5 --- .claude/reference/information-architecture.md | 24 +++- docs/codacy-cloud-cli/index.md | 18 +-- docs/codacy-skills/index.md | 119 ++++++++++++++++++ docs/coverage-reporter/index.md | 2 +- docs/developer-tools/index.md | 7 +- .../configuring-code-patterns.md | 4 +- mkdocs.yml | 3 + .../ionicons/svg/document-text-outline.svg | 1 + 8 files changed, 161 insertions(+), 17 deletions(-) create mode 100644 docs/codacy-skills/index.md create mode 100644 theme/assets/vendor/ionicons/svg/document-text-outline.svg diff --git a/.claude/reference/information-architecture.md b/.claude/reference/information-architecture.md index 7413886e8e..80377934b0 100644 --- a/.claude/reference/information-architecture.md +++ b/.claude/reference/information-architecture.md @@ -28,7 +28,29 @@ Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a s ## Codacy Skills' home -Skills is a natural-language wrapper around Codacy Cloud CLI specifically, not general-purpose agent access to all of Codacy — the CLI's own page already frames it that way ("Pair it with Codacy Skills to interact with your Codacy data in plain language"). It belongs under Codacy Cloud CLI, not in a standalone agent-tools section. +**Superseded, 2026-09-09.** Codacy Skills gets its own section under "Developer tools", as a sibling of "Codacy CLIs" — not a subsection of the Codacy Cloud CLI page. + +The earlier decision filed Skills under Codacy Cloud CLI on the grounds that it was "a natural-language wrapper around Codacy Cloud CLI specifically". That premise doesn't hold against [`codacy/codacy-skills`](https://github.com/codacy/codacy-skills). Six skills ship there, and only one of them wraps the Cloud CLI: + +| Skill | Drives | +|---|---| +| `codacy-cloud-cli` | Codacy Cloud CLI | +| `configure-codacy-cloud` | Cloud CLI, plus the Analysis CLI for config files | +| `codacy-code-review` | Both CLIs | +| `configure-codacy` | Analysis CLI first, Cloud CLI to check the repo is on Codacy | +| `codacy-analysis-cli` | Codacy Analysis CLI only | +| `setup-coverage` | Neither — coverage tooling and CI | + +Three of the six center on the Codacy Analysis CLI, which has no page anywhere under `docs/`, and two need no Cloud CLI at all. Filing all six under the Cloud CLI page misdescribes them and leaves five of the six named nowhere on the site. + +Skills still passes the direction-of-consumption test for "Developer tools" — the reader's own agent is the caller — so the tab is unchanged. Only the level within it moves. + +Two constraints on carrying this out: + +- **Keep `#install-the-codacy-skills` alive on `codacy-cloud-cli/index.md`.** Four inbound links inside this repo point at it, and the product UI, blog, and support macros are invisible to any check here. Leave the heading and its explicit `{: id=...}` in place as a pointer to the new page rather than deleting it. +- **The Analysis CLI gap is separate work.** Documenting it would also fix "Codacy CLIs" being a plural section holding one page. Don't let it ride along with the Skills page. + +Related: the standalone-page request came from marketing, which makes the *prominence* half of this a positioning call — see "A structural move can still be the wrong call for reasons outside IA" below. ## A structural move can still be the wrong call for reasons outside IA diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md index 5a3a259dd9..e573c55328 100644 --- a/docs/codacy-cloud-cli/index.md +++ b/docs/codacy-cloud-cli/index.md @@ -6,7 +6,7 @@ description: Install and use the Codacy Cloud CLI to manage your repositories, i The Codacy Cloud CLI gives you a fast terminal interface to your Codacy data. Add repositories, review issues, investigate security findings, inspect pull requests, and configure tools—all without opening a browser. -Pair it with [Codacy Skills](#install-the-codacy-skills) to interact with your Codacy data in plain language directly from your AI assistant. +Pair it with the [Codacy Skills](../codacy-skills/index.md) to interact with your Codacy data in plain language directly from your AI assistant.
@@ -50,22 +50,16 @@ When more than one credential is available, the CLI uses the first of the option ## Install the Codacy Skills {: id="install-the-codacy-skills"} -The [Codacy Skills](https://github.com/codacy/codacy-skills) let your AI assistant interact with your Codacy data in plain language, without needing to remember command syntax: +The [Codacy Skills](../codacy-skills/index.md) let your AI assistant interact with your Codacy data in plain language, without needing to remember command syntax. The `codacy-cloud-cli` skill covers this CLI; five other skills cover local analysis, pull request review, configuration, and coverage. -- "Show me the critical security findings in my org" -- "What issues were introduced in PR #42?" -- "Ignore all false positives in the last pull request" - -**Claude Code** (recommended): +For Claude Code: ```bash claude plugin marketplace add codacy/codacy-skills claude plugin install codacy-skills@codacy ``` -**Claude.ai**: download the skill folder, zip it, and upload it under **Settings > Capabilities > Skills**. - -If you use a different AI assistant, visit the [Codacy Skills repository](https://github.com/codacy/codacy-skills) to install the skills directly. +See [Codacy Skills](../codacy-skills/index.md#install-the-skills) for the other assistants. ## What you can do @@ -265,7 +259,7 @@ Feed both outputs to Claude Code (with the Codacy skill installed) to decide wha ### Audit affected functions across one or multiple repositories {: id="affected-functions-scale"} -The [affected functions](#affected-functions) shown for a single finding tell you whether one vulnerable dependency is reachable. To check vulnerable dependencies across one or multiple repositories at once, [install the Codacy Skills](#install-the-codacy-skills) — the `codacy-cloud-cli` skill already knows how to pull SCA findings for one or more repositories, tell direct from transitive dependencies apart, and check whether the affected functions are actually used. +The [affected functions](#affected-functions) shown for a single finding tell you whether one vulnerable dependency is reachable. To check vulnerable dependencies across one or multiple repositories at once, [install the Codacy Skills](../codacy-skills/index.md) — the `codacy-cloud-cli` skill already knows how to pull SCA findings for one or more repositories, tell direct from transitive dependencies apart, and check whether the affected functions are actually used. With the skill installed and local checkouts of the repositories you want to cover, ask your assistant directly, for example: @@ -297,7 +291,7 @@ From there, pipe the JSON output to `jq`, post results as PR comments with the [ ## See also - [Codacy Cloud CLI on GitHub](https://github.com/codacy/codacy-cloud-cli) -- [Codacy Skills on GitHub](https://github.com/codacy/codacy-skills) +- [Codacy Skills](../codacy-skills/index.md) - [API tokens](../codacy-api/api-tokens.md) - [Using the Codacy API](../codacy-api/using-the-codacy-api.md) - [GitHub integration and AI Reviewer](../repositories-configure/integrations/github-integration.md#ai-reviewer) diff --git a/docs/codacy-skills/index.md b/docs/codacy-skills/index.md new file mode 100644 index 0000000000..a529a58541 --- /dev/null +++ b/docs/codacy-skills/index.md @@ -0,0 +1,119 @@ +--- +description: Install the Codacy Skills to let your AI assistant query your Codacy data, review pull requests, configure analysis, and set up coverage in plain language. +--- + +# Codacy Skills + +The Codacy Skills teach your AI coding assistant how to drive Codacy: they tell it which command to run, how to read the output, and what to do next. You describe what you want in plain language instead of remembering command syntax. + +The skills are open source under the MIT license and live in the [codacy/codacy-skills](https://github.com/codacy/codacy-skills) repository. They follow the [Agent Skills](https://agentskills.io/) standard, so they work with Claude Code, Claude.ai, OpenAI Codex, GitHub Copilot, Gemini CLI, and any other assistant that supports it. + +## Available skills + +| Skill | What it does | Needs | +|---|---|---| +| `codacy-cloud-cli` | Queries repositories, issues, security findings, pull requests, tools, and patterns on Codacy Cloud | Codacy Cloud CLI | +| `codacy-code-review` | Adds Codacy issues, security findings, coverage, and duplication to a pull request review | Both CLIs | +| `codacy-analysis-cli` | Runs static analysis locally, without sending your code to Codacy | Codacy Analysis CLI | +| `configure-codacy` | Discovers your project's stack, enables the tools and patterns that fit it, and cuts noise from the results | Both CLIs | +| `configure-codacy-cloud` | Tunes the configuration of a repository already analyzed on Codacy, without running local analysis | Both CLIs | +| `setup-coverage` | Detects your test framework and CI, then adds what's missing to generate and upload coverage reports | A repository on Codacy | + +The skills work together. Ask your assistant to review a pull request and it uses `codacy-code-review`, which in turn reaches for the two CLI skills to get local analysis and cloud coverage data. + +!!! note + The Codacy Cloud CLI (`codacy`) and the Codacy Analysis CLI (`codacy-analysis`) are different tools. The Cloud CLI queries your data on Codacy; the Analysis CLI runs analyzers on your machine. + +## Requirements + +Install the CLIs the skills you want depend on: + +```bash +npm install -g @codacy/codacy-cloud-cli +npm install -g @codacy/analysis-cli +``` + +Then authenticate. Run `codacy login` and paste an [account API token](../codacy-api/api-tokens.md#account-api-tokens), or set the `CODACY_API_TOKEN` environment variable for non-interactive environments. Both CLIs read the same credentials from `~/.codacy/credentials`, so a single login covers both. + +See [Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication) for the full set of authentication options, including repository API tokens. + +## Install the skills + +How you install the skills depends on your assistant. + +### Claude Code + +Add the Codacy marketplace, then install the plugin: + +```bash +claude plugin marketplace add codacy/codacy-skills +claude plugin install codacy-skills@codacy +``` + +### Claude.ai + +Download the folder of the skill you want from the repository, zip it, and upload it under **Settings > Capabilities > Skills > Upload skill**. Repeat for each skill you want. + +### OpenAI Codex + +Codex discovers skills from an `.agents/skills/` directory. The repository already points at each skill from that path, so cloning it is enough: + +```bash +git clone https://github.com/codacy/codacy-skills ~/.codacy-skills + +# For a single project, from the project's root directory +ln -s ~/.codacy-skills/.agents/skills .agents/skills + +# Or for every project +ln -s ~/.codacy-skills/.agents/skills ~/.agents/skills +``` + +### GitHub Copilot + +Copilot's coding agent reads an `AGENTS.md` file from the root of your repository: + +```bash +curl -o AGENTS.md https://raw.githubusercontent.com/codacy/codacy-skills/master/AGENTS.md +``` + +If your repository already has an `AGENTS.md`, merge the two files instead of overwriting yours. + +### Gemini CLI + +```bash +gemini extensions install https://github.com/codacy/codacy-skills.git --consent +``` + +## Keep the skills up to date + +The skills change as the CLIs gain commands, so update them periodically: + +- **Claude Code:** `claude plugin update` +- **OpenAI Codex:** `git -C ~/.codacy-skills pull` +- **Claude.ai:** download and upload the skill folder again + +## What you can ask for + +Once the skills are installed, describe the outcome you want rather than the command: + +```text +Show me the critical security findings in my org +What issues were introduced in PR #42? +Ignore all false positives in the last pull request +Set up coverage reporting for this repository +``` + +Your assistant picks the skill that matches, runs the underlying commands, and reports back. Two workflows are documented in more detail elsewhere: + +- [Auditing vulnerable dependencies across repositories](../codacy-cloud-cli/index.md#affected-functions-scale) with `codacy-cloud-cli`. +- [Running auto-configuration locally](../repositories-configure/configuring-code-patterns.md#running-it-with-codacy-skills) with `configure-codacy`, which works on any plan. + +!!! note + A skill runs the CLIs with your credentials and acts on what it finds. Review what it proposes before letting it ignore findings, change your tool configuration, or upgrade a dependency. + +## See also + +- [Codacy Skills on GitHub](https://github.com/codacy/codacy-skills) +- [Codacy Cloud CLI](../codacy-cloud-cli/index.md) +- [API tokens](../codacy-api/api-tokens.md) +- [Adding coverage to your repository](../coverage-reporter/index.md) diff --git a/docs/coverage-reporter/index.md b/docs/coverage-reporter/index.md index ac748a8f59..70b8fcb9b5 100644 --- a/docs/coverage-reporter/index.md +++ b/docs/coverage-reporter/index.md @@ -5,7 +5,7 @@ description: Generate coverage reports in a supported format and upload them to # Adding coverage to your repository !!! tip - Setting up Coverage is now easier. Use our new Codacy skill to automatically generate and upload your coverage reports. [Learn how to use it](https://github.com/codacy/codacy-skills/blob/master/skills/setup-coverage/SKILL.md) + Setting up Coverage is now easier. Use our new Codacy skill to automatically generate and upload your coverage reports. [Learn how to use it](../codacy-skills/index.md) Code coverage is a metric used to describe the degree to which the source code of a program is tested. A program with high code coverage has been more thoroughly tested and has a lower chance of containing software bugs than a program with low code coverage. You can read more about the [basics of code coverage](https://blog.codacy.com/a-guide-to-code-coverage-part-1-code-coverage-explained/) on Codacy's blog. diff --git a/docs/developer-tools/index.md b/docs/developer-tools/index.md index 15e0f51073..9686d67bc8 100644 --- a/docs/developer-tools/index.md +++ b/docs/developer-tools/index.md @@ -22,7 +22,12 @@ Codacy also works from outside the Codacy web app: from your terminal, your IDE,

Codacy Cloud CLI

-

Add repositories, review issues, and inspect pull requests from your terminal. Pair it with Codacy Skills to ask for the same in plain language from your AI assistant.

+

Add repositories, review issues, and inspect pull requests from your terminal.

+ + + +

Codacy Skills

+

Teach your AI assistant to run the Codacy CLIs, so you can ask for issues, reviews, configuration, and coverage in plain language.

 diff --git a/docs/repositories-configure/configuring-code-patterns.md b/docs/repositories-configure/configuring-code-patterns.md index 8537529e09..712fb6494e 100644 --- a/docs/repositories-configure/configuring-code-patterns.md +++ b/docs/repositories-configure/configuring-code-patterns.md @@ -76,9 +76,9 @@ There are two ways to run it. ### Running it with Codacy Skills {: id="running-it-with-codacy-skills"} -If you'd rather run auto-configuration locally with your own AI agent, use the `configure-codacy` [skill](../codacy-cloud-cli/index.md#install-the-codacy-skills) instead. This option is open-source and isn't limited to paid plans. +If you'd rather run auto-configuration locally with your own AI agent, use the `configure-codacy` [skill](../codacy-skills/index.md) instead. This option is open-source and isn't limited to paid plans. -1. [Install the Codacy Skills](../codacy-cloud-cli/index.md#install-the-codacy-skills). +1. [Install the Codacy Skills](../codacy-skills/index.md#install-the-skills). 1. Open a terminal in your repository's root directory and run the skill: ```bash diff --git a/mkdocs.yml b/mkdocs.yml index 7e282e2ae3..72d0291b0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ extra: "Getting started": "rocket-outline" "Codacy Guardrails": "shield-checkmark-outline" "Codacy CLIs": "terminal-outline" + "Codacy Skills": "document-text-outline" "IDE integrations": "share-social-outline" "Codacy AI": "sparkles-outline" "Repositories on Codacy": "folder-open-outline" @@ -769,6 +770,8 @@ nav: - codacy-api/examples/triggering-dast-scans.md - Codacy CLIs: - codacy-cloud-cli/index.md + - Codacy Skills: + - codacy-skills/index.md - IDE integrations: - getting-started/integrating-codacy-with-visual-studio-code.md - getting-started/integrating-codacy-with-intellij-ides.md diff --git a/theme/assets/vendor/ionicons/svg/document-text-outline.svg b/theme/assets/vendor/ionicons/svg/document-text-outline.svg new file mode 100644 index 0000000000..c701fa7102 --- /dev/null +++ b/theme/assets/vendor/ionicons/svg/document-text-outline.svg @@ -0,0 +1 @@ + From 2a4e3274c3b29bec126daf2bac2742736f392127 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 12:44:19 +0100 Subject: [PATCH 2/7] docs: state the Skills IA decision as a durable rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section recorded a dated supersession and a table of the six skills that happened to ship. Both go stale: the count changes, and the date framing turns a standing decision into a changelog entry. State the rule instead — a family of skills spanning several tools does not nest under one of them — and keep the anchor constraint, which applies to any future move rather than to this one change. Co-Authored-By: Claude Opus 5 --- .claude/reference/information-architecture.md | 24 ++++--------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/.claude/reference/information-architecture.md b/.claude/reference/information-architecture.md index 80377934b0..a0f0fc5a0e 100644 --- a/.claude/reference/information-architecture.md +++ b/.claude/reference/information-architecture.md @@ -28,29 +28,15 @@ Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a s ## Codacy Skills' home -**Superseded, 2026-09-09.** Codacy Skills gets its own section under "Developer tools", as a sibling of "Codacy CLIs" — not a subsection of the Codacy Cloud CLI page. +Codacy Skills is its own section under "Developer tools", a sibling of "Codacy CLIs" — not a subsection of any single tool's page. -The earlier decision filed Skills under Codacy Cloud CLI on the grounds that it was "a natural-language wrapper around Codacy Cloud CLI specifically". That premise doesn't hold against [`codacy/codacy-skills`](https://github.com/codacy/codacy-skills). Six skills ship there, and only one of them wraps the Cloud CLI: +The test is **how many things a family of skills spans**. Skills is a set, not a feature of one tool: some members drive the Codacy Cloud CLI, some the Codacy Analysis CLI, some both, and some neither. Nesting the set under one of its members misdescribes the rest and leaves them unnamed anywhere on the site. That reasoning holds however many skills ship and whatever they cover — check the current set in [`codacy/codacy-skills`](https://github.com/codacy/codacy-skills) rather than assuming a count. -| Skill | Drives | -|---|---| -| `codacy-cloud-cli` | Codacy Cloud CLI | -| `configure-codacy-cloud` | Cloud CLI, plus the Analysis CLI for config files | -| `codacy-code-review` | Both CLIs | -| `configure-codacy` | Analysis CLI first, Cloud CLI to check the repo is on Codacy | -| `codacy-analysis-cli` | Codacy Analysis CLI only | -| `setup-coverage` | Neither — coverage tooling and CI | +The tab is not in question: Skills passes the direction-of-consumption test above, since the reader's own agent is the caller. Only the level within the tab was ever the argument. -Three of the six center on the Codacy Analysis CLI, which has no page anywhere under `docs/`, and two need no Cloud CLI at all. Filing all six under the Cloud CLI page misdescribes them and leaves five of the six named nowhere on the site. +One durable constraint if the page ever moves again: **`codacy-cloud-cli/index.md` must keep its `#install-the-codacy-skills` anchor.** Skills lived on that page first, and inbound links from the product UI, blog, and support macros are invisible to every check in this repo. Leave the heading and its explicit `{: id=...}` in place as a pointer, whatever the page it points at. -Skills still passes the direction-of-consumption test for "Developer tools" — the reader's own agent is the caller — so the tab is unchanged. Only the level within it moves. - -Two constraints on carrying this out: - -- **Keep `#install-the-codacy-skills` alive on `codacy-cloud-cli/index.md`.** Four inbound links inside this repo point at it, and the product UI, blog, and support macros are invisible to any check here. Leave the heading and its explicit `{: id=...}` in place as a pointer to the new page rather than deleting it. -- **The Analysis CLI gap is separate work.** Documenting it would also fix "Codacy CLIs" being a plural section holding one page. Don't let it ride along with the Skills page. - -Related: the standalone-page request came from marketing, which makes the *prominence* half of this a positioning call — see "A structural move can still be the wrong call for reasons outside IA" below. +Two things this decision deliberately does not settle. Whether the Codacy Analysis CLI gets its own page is a separate question — answering it would also resolve "Codacy CLIs" being a plural section, and neither depends on where Skills lives. And the prominence of a standalone section is a positioning call rather than a structural one, per the section below. ## A structural move can still be the wrong call for reasons outside IA From cc6bcb7b9f9a6006f9c2e4a2bf985ad87e84ff46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 12:48:13 +0100 Subject: [PATCH 3/7] fix: clear Vale on the lines this branch adds The Vale check runs with filter_mode: added, and reviewdog exits non-zero on any result, so findings on new lines fail the build even though the action sets fail_on_error: false. - Register CLIs in the shared vocabulary. mkdocs.yml names the section "Codacy CLIs", so the plural is a repo term rather than a misspelling. - Wrap the codacy/codacy-skills repo slug in backticks. Inline code is an IgnoredScope, and the slug is a path rather than prose. - Reword three sentences that tripped Microsoft.Terms, .Contractions, and .Dashes. Co-Authored-By: Claude Opus 5 --- .github/styles/config/vocabularies/Codacy/accept.txt | 1 + docs/codacy-cloud-cli/index.md | 2 +- docs/codacy-skills/index.md | 6 +++--- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/styles/config/vocabularies/Codacy/accept.txt b/.github/styles/config/vocabularies/Codacy/accept.txt index 7062e79bca..5ffaa4fe82 100644 --- a/.github/styles/config/vocabularies/Codacy/accept.txt +++ b/.github/styles/config/vocabularies/Codacy/accept.txt @@ -14,6 +14,7 @@ bundler-audit Checkov Checkstyle Clang-Tidy +CLIs cloc CloudFormation Cobertura diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md index e573c55328..5238049c2a 100644 --- a/docs/codacy-cloud-cli/index.md +++ b/docs/codacy-cloud-cli/index.md @@ -259,7 +259,7 @@ Feed both outputs to Claude Code (with the Codacy skill installed) to decide wha ### Audit affected functions across one or multiple repositories {: id="affected-functions-scale"} -The [affected functions](#affected-functions) shown for a single finding tell you whether one vulnerable dependency is reachable. To check vulnerable dependencies across one or multiple repositories at once, [install the Codacy Skills](../codacy-skills/index.md) — the `codacy-cloud-cli` skill already knows how to pull SCA findings for one or more repositories, tell direct from transitive dependencies apart, and check whether the affected functions are actually used. +The [affected functions](#affected-functions) shown for a single finding tell you whether one vulnerable dependency is reachable. To check vulnerable dependencies across one or multiple repositories at once, [install the Codacy Skills](../codacy-skills/index.md). The `codacy-cloud-cli` skill already knows how to pull SCA findings for one or more repositories, tell direct from transitive dependencies apart, and check whether the affected functions are actually used. With the skill installed and local checkouts of the repositories you want to cover, ask your assistant directly, for example: diff --git a/docs/codacy-skills/index.md b/docs/codacy-skills/index.md index a529a58541..ad6e4ebeb0 100644 --- a/docs/codacy-skills/index.md +++ b/docs/codacy-skills/index.md @@ -6,7 +6,7 @@ description: Install the Codacy Skills to let your AI assistant query your Codac The Codacy Skills teach your AI coding assistant how to drive Codacy: they tell it which command to run, how to read the output, and what to do next. You describe what you want in plain language instead of remembering command syntax. -The skills are open source under the MIT license and live in the [codacy/codacy-skills](https://github.com/codacy/codacy-skills) repository. They follow the [Agent Skills](https://agentskills.io/) standard, so they work with Claude Code, Claude.ai, OpenAI Codex, GitHub Copilot, Gemini CLI, and any other assistant that supports it. +The skills are open source under the MIT license and live in the [`codacy/codacy-skills`](https://github.com/codacy/codacy-skills) repository. They follow the [Agent Skills](https://agentskills.io/) standard, so they work with Claude Code, Claude.ai, OpenAI Codex, GitHub Copilot, Gemini CLI, and any other assistant that supports it. ## Available skills @@ -22,7 +22,7 @@ The skills are open source under the MIT license and live in the [codacy/codacy- The skills work together. Ask your assistant to review a pull request and it uses `codacy-code-review`, which in turn reaches for the two CLI skills to get local analysis and cloud coverage data. !!! note - The Codacy Cloud CLI (`codacy`) and the Codacy Analysis CLI (`codacy-analysis`) are different tools. The Cloud CLI queries your data on Codacy; the Analysis CLI runs analyzers on your machine. + The Codacy Cloud CLI (`codacy`) and the Codacy Analysis CLI (`codacy-analysis`) are different tools. Use `codacy` to query your data on Codacy, and `codacy-analysis` to run analyzers on your machine. ## Requirements @@ -56,7 +56,7 @@ Download the folder of the skill you want from the repository, zip it, and uploa ### OpenAI Codex -Codex discovers skills from an `.agents/skills/` directory. The repository already points at each skill from that path, so cloning it is enough: +Codex discovers skills from an `.agents/skills/` directory. The repository already points at each skill from that path, so cloning the repository is enough: ```bash git clone https://github.com/codacy/codacy-skills ~/.codacy-skills From 7d85932b1d1e2e93832dd7cba8299e4edead435c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 12:52:08 +0100 Subject: [PATCH 4/7] docs: trim the Skills IA entry to the decision and its reason Two paragraphs were carrying detail the file does not need: the anchor constraint is already enforced by the heading in codacy-cloud-cli/index.md and by the general anchor rule in CLAUDE.md, and the list of questions the decision does not settle is not a decision. Leaves the entry the same length as its neighbours in this file. Co-Authored-By: Claude Opus 5 --- .claude/reference/information-architecture.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.claude/reference/information-architecture.md b/.claude/reference/information-architecture.md index a0f0fc5a0e..6e512a54f2 100644 --- a/.claude/reference/information-architecture.md +++ b/.claude/reference/information-architecture.md @@ -30,13 +30,7 @@ Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a s Codacy Skills is its own section under "Developer tools", a sibling of "Codacy CLIs" — not a subsection of any single tool's page. -The test is **how many things a family of skills spans**. Skills is a set, not a feature of one tool: some members drive the Codacy Cloud CLI, some the Codacy Analysis CLI, some both, and some neither. Nesting the set under one of its members misdescribes the rest and leaves them unnamed anywhere on the site. That reasoning holds however many skills ship and whatever they cover — check the current set in [`codacy/codacy-skills`](https://github.com/codacy/codacy-skills) rather than assuming a count. - -The tab is not in question: Skills passes the direction-of-consumption test above, since the reader's own agent is the caller. Only the level within the tab was ever the argument. - -One durable constraint if the page ever moves again: **`codacy-cloud-cli/index.md` must keep its `#install-the-codacy-skills` anchor.** Skills lived on that page first, and inbound links from the product UI, blog, and support macros are invisible to every check in this repo. Leave the heading and its explicit `{: id=...}` in place as a pointer, whatever the page it points at. - -Two things this decision deliberately does not settle. Whether the Codacy Analysis CLI gets its own page is a separate question — answering it would also resolve "Codacy CLIs" being a plural section, and neither depends on where Skills lives. And the prominence of a standalone section is a positioning call rather than a structural one, per the section below. +Skills is a set, not a feature of one tool: some members drive the Codacy Cloud CLI, some the Codacy Analysis CLI, some both, and some neither. Nesting the set under one of its members misdescribes the rest. The tab itself was never in question — Skills passes the direction-of-consumption test above, since the reader's own agent is the caller. ## A structural move can still be the wrong call for reasons outside IA From ca0baf279e6742f2522b3b5a2147c7a00755a0ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 12:57:41 +0100 Subject: [PATCH 5/7] docs: drop stale premises from the Guardrails IA entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both Guardrails entries described the nav as it was before #2733, the same commit that created this file: they argued from a "(IDE Extension)" nav title that commit removed, and treated the move into Developer tools as a change still to be considered after it had been made. Keep what does not expire — Guardrails classifies as a developer tool however it is installed, its setup page must not be split across generic sections, and prominence is a positioning call rather than a structural one — and cut the snapshot around it. Co-Authored-By: Claude Opus 5 --- .claude/reference/information-architecture.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/reference/information-architecture.md b/.claude/reference/information-architecture.md index 6e512a54f2..4f69c30e7f 100644 --- a/.claude/reference/information-architecture.md +++ b/.claude/reference/information-architecture.md @@ -20,11 +20,11 @@ Both involve AI; the test is **who's calling whom**, not whether the word "AI" a `organizations/ai-risk-hub.md` is neither bucket despite the name — it's governance over AI-generated code risk in the reader's own repositories, correctly filed under Organizations. -## Why Codacy Guardrails counts as a developer tool, not just an IDE extension +## Why Codacy Guardrails counts as a developer tool -The nav title "(IDE Extension)" on this section describes one delivery path, not the product. `codacy-guardrails-getting-started.md`'s "How to install - Manually" section sets up the identical capability — Analysis CLI, MCP Server, AI rules — with no IDE extension involved. Guardrails passes the direction-of-consumption test on its own terms, independent of how it's installed. +Guardrails passes the direction-of-consumption test on its own terms, whatever its delivery path. Its manual install sets up the same capability — Analysis CLI, MCP Server, AI rules — with no IDE extension involved, so don't refile it as an IDE integration on the strength of one install path. -Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a single page, in service of one outcome. Don't split that content to file separate pieces under generic "CLIs" or "MCP" sections — the split breaks the page's `#install-cli` / `#install-mcp-server` anchors for any inbound link outside this repo (product UI, blog, support macros), and there's no config-level fix for an anchor that moves to a different page. Move the whole section as one unit; don't extract from it. +Its setup content is one continuous flow inside a single page. Don't split it to file pieces under generic "CLIs" or "MCP" sections: that breaks the page's `#install-cli` and `#install-mcp-server` anchors for inbound links outside this repo, and an anchor that moves to another page has no config-level fix. Move the section as a unit; don't extract from it. ## Codacy Skills' home @@ -34,7 +34,7 @@ Skills is a set, not a feature of one tool: some members drive the Codacy Cloud ## A structural move can still be the wrong call for reasons outside IA -Guardrails currently sits prominently under "Getting started" with active marketing behind it (a blog-post CTA). Relocating it into "Developer tools" is IA-correct by the test above, but it's also a visibility change for a product someone may be actively driving signups to. That's a positioning call, not a structure call — flag it to whoever owns that placement rather than deciding it here. +Where a section sits sets how visible it is, and a product with marketing driving signups to it may be placed for that reason rather than for IA. When a move is IA-correct but changes prominence, flag it to whoever owns the placement instead of deciding it here. ## See also From 32ccb2079728b2c58e3ee0c4728e0bddf9ab8b19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 13:00:49 +0100 Subject: [PATCH 6/7] docs: remove the overview video from the Codacy Cloud CLI page Co-Authored-By: Claude Opus 5 --- docs/codacy-cloud-cli/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md index 5238049c2a..2f48f7cefc 100644 --- a/docs/codacy-cloud-cli/index.md +++ b/docs/codacy-cloud-cli/index.md @@ -8,8 +8,6 @@ The Codacy Cloud CLI gives you a fast terminal interface to your Codacy data. Ad Pair it with the [Codacy Skills](../codacy-skills/index.md) to interact with your Codacy data in plain language directly from your AI assistant. -
- ## Installation Install the CLI using npm: From fe3f6a1ebccebf7e8b2f66533da007cd308d90e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 9 Sep 2026 13:04:21 +0100 Subject: [PATCH 7/7] docs: cover Copilot and Gemini CLI in the update instructions The list covered three of the five install paths. Add the other two and reorder to match the install section. Copilot has no update mechanism: the install copies AGENTS.md into the reader's repository, so it goes stale silently and has to be re-downloaded and merged. Gemini CLI's command comes from its extensions reference, which also documents the restart. Co-Authored-By: Claude Opus 5 --- docs/codacy-skills/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/codacy-skills/index.md b/docs/codacy-skills/index.md index ad6e4ebeb0..3d0ba68df4 100644 --- a/docs/codacy-skills/index.md +++ b/docs/codacy-skills/index.md @@ -86,11 +86,13 @@ gemini extensions install https://github.com/codacy/codacy-skills.git --consent ## Keep the skills up to date -The skills change as the CLIs gain commands, so update them periodically: +The skills change as the CLIs gain commands, so update them periodically. How you do that depends on how you installed them: - **Claude Code:** `claude plugin update` +- **Claude.ai:** download and upload the skill folder again, replacing the existing one - **OpenAI Codex:** `git -C ~/.codacy-skills pull` -- **Claude.ai:** download and upload the skill folder again +- **GitHub Copilot:** download `AGENTS.md` again and merge it into yours. The install copies the file into your repository rather than linking to it, so it never updates on its own. +- **Gemini CLI:** `gemini extensions update codacy-skills`. Restart the CLI afterward for the change to take effect. ## What you can ask for