docs: add Codacy Skills section under Developer tools

.claude/reference/information-architecture.md

@@ -20,19 +20,21 @@ 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
 
-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.
+Codacy Skills is its own section under "Developer tools", a sibling of "Codacy CLIs" — not a subsection of any single tool's page.
+
+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
 
-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
 

.github/styles/config/vocabularies/Codacy/accept.txt

@@ -14,6 +14,7 @@ bundler-audit
 Checkov
 Checkstyle
 Clang-Tidy
+CLIs
 cloc
 CloudFormation
 Cobertura

docs/codacy-cloud-cli/index.md

@@ -6,9 +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.
-
-<div style="position: relative; padding-bottom: 61.224489795918366%; height: 0;"><iframe src="https://www.loom.com/embed/1960b3f07f2c419682a1e22e2b2928d1" title="Codacy Cloud CLI overview video" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;"></iframe></div>
+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
 
@@ -50,22 +48,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:
-
-- "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"
+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.
 
-**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 +257,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 +289,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)

docs/codacy-skills/index.md

@@ -0,0 +1,121 @@
+---
+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. Use `codacy` to query your data on Codacy, and `codacy-analysis` to run 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 the repository 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. 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`
+-   **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
+
+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)

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 <span class="skip-vale">thoroughly</span> 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.
 

docs/developer-tools/index.md

@@ -22,7 +22,12 @@ Codacy also works from outside the Codacy web app: from your terminal, your IDE,
 
     <a class="content-link" href="../codacy-cloud-cli/">
       <h3>Codacy Cloud CLI</h3>
-      <p>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.</p>
+      <p>Add repositories, review issues, and inspect pull requests from your terminal.</p>
+    </a>
+
+    <a class="content-link" href="../codacy-skills/">
+      <h3>Codacy Skills</h3>
+      <p>Teach your AI assistant to run the Codacy CLIs, so you can ask for issues, reviews, configuration, and coverage in plain language.</p>
     </a>
 
     <a class="content-link" href="../getting-started/integrating-codacy-with-visual-studio-code/">

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

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