# Agent Skills & Plugin

Install the SigNoz plugin and Agent Skills so AI agents like Claude Code, Codex, Cursor, and Gemini can query data, build dashboards, manage alerts, and explore SigNoz docs.

> For the complete documentation index, see [llms.txt](https://signoz.io/llms.txt). Markdown versions are also available by appending `.md` to documentation URLs.

Tags: SigNoz Cloud, Self-Host

[Agent Skills](https://agentskills.io) are an open format for extending AI coding agents with specialized knowledge and capabilities. Once installed, your agent uses them whenever it detects a relevant task - no prompting required.

When you ask your AI agent something like "why did this alert fire," "create a dashboard for my Postgres database," or "write a ClickHouse query for these logs," the agent picks the matching skill and follows its instructions.

SigNoz ships these skills two ways:

- **The SigNoz plugin** - the recommended path. One install bundles every skill plus the MCP server registration, so your agent can both reason about SigNoz *and* act on your data. Available for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Gemini CLI, Devin CLI, Grok Build, and Antigravity CLI.
- **Individual skills via skills.sh** - install one or more skill files on their own, for any skills.sh-compatible agent.

## Install the plugin

### Claude Code

1. Add the marketplace and install the plugin:

   ```
   /plugin marketplace add SigNoz/agent-skills
   /plugin install signoz@signoz-skills
   ```

2. When prompted for your **SigNoz MCP endpoint**:

   - **SigNoz Cloud** - use `https://mcp.<region>.signoz.cloud/mcp` and replace `<region>` with your region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`). Find your region under **Settings → Ingestion** in SigNoz, or see the [region reference](https://signoz.io/docs/ingestion/signoz-cloud/overview/#how-do-i-find-my-ingestion-url).
   - **Self-Hosted SigNoz** - enter your own HTTP `/mcp` URL instead, for example `http://localhost:8000/mcp`.

3. Run `/mcp`, select the `signoz` server, and complete the authentication flow if prompted.

To change the endpoint later, reconfigure the plugin's options or run `signoz-mcp-setup` with the new region or MCP URL.

To update after new releases:

```
/plugin marketplace update
/plugin update signoz@signoz-skills
```

> **Note**
>
> The plugin ships a `PreToolUse` hook that auto-allows `WebFetch` to `signoz.io` domains. This does not affect `Bash`-based network calls (`curl`, `wget`), which follow the normal permission flow.

### Codex

Add the marketplace:

```
codex plugin marketplace add SigNoz/agent-skills
```

Then, in a Codex session started from your project:

1. Run `/plugins`, open the **SigNoz** marketplace, and install `signoz`.

2. Point the MCP server at your instance with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL:

   ```
   signoz-mcp-setup <region>
   ```

3. Authenticate over OAuth and verify the connection:

   ```
   codex mcp login signoz
   codex mcp list   # signoz -> enabled, Auth = logged in
   ```

### Cursor

The plugin is not yet on the public Cursor Marketplace, so install it through a Team Marketplace:

1. Add `https://github.com/SigNoz/agent-skills` as a team marketplace under **Settings → Plugins**.
2. Install the `signoz` plugin from the marketplace panel. When prompted for your **SigNoz Region**, select your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`) or choose **self-hosted**. Cloud regions fill in `https://mcp.<region>.signoz.cloud/mcp` automatically.
3. Self-hosted only: run `/signoz-mcp-setup` in an agent chat with your HTTP MCP URL (for example `/signoz-mcp-setup http://localhost:8000/mcp`). Until then, the MCP endpoint stays unconfigured. SigNoz Cloud users can skip this step.
4. Reload Cursor, then open MCP settings and complete authentication for the `signoz` server if prompted.

To change the region or endpoint later, run `/signoz-mcp-setup` again with the correct region or URL and reload Cursor.

### VS Code / GitHub Copilot

These steps install the SigNoz plugin for GitHub Copilot in VS Code.

1. Open GitHub Copilot Chat in VS Code and confirm that you are signed in.

2. Open the Command Palette and run **Chat: Install Plugin From Source**.

3. Enter `https://github.com/SigNoz/agent-skills`, then select `signoz` if prompted.

4. Return to Copilot Chat, select **Agent** mode, and run the setup skill with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`) or a self-hosted HTTP MCP URL:

   ```
   /signoz:signoz-mcp-setup <region-or-mcp-url>
   ```

5. Approve the `signoz` MCP server if prompted, then complete authentication. Self-hosted endpoints need no OAuth unless the server runs with `OAUTH_ENABLED=true`.

### Gemini CLI

Install the extension:

```
gemini extensions install https://github.com/SigNoz/agent-skills
```

When prompted for the **SigNoz MCP endpoint**, enter `https://mcp.<region>.signoz.cloud/mcp` with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`), or your self-hosted URL (for example `http://localhost:8000/mcp`). Then authenticate:

```
/mcp auth signoz
```

Follow the prompts to enter your SigNoz instance URL and API key.

### Devin CLI

1. Install the plugin:

   ```
   devin plugins install SigNoz/agent-skills
   ```

   This installs at user level and works across all projects. Devin's plugin system does not bundle MCP servers or prompt for install-time config, so the next steps set that up.

2. In a Devin session, run the setup skill with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL. Devin namespaces plugin skills as `/<plugin>:<skill>`, so it's invoked as `/signoz:signoz-mcp-setup`:

   ```
   /signoz:signoz-mcp-setup <region-or-mcp-url>
   ```

   This writes a `signoz` entry into the highest-precedence Devin config scope that already has one, or `~/.config/devin/config.json` by default.

3. Authenticate:

   - **SigNoz Cloud** - start a new session and run `devin mcp login signoz` to complete OAuth.
   - **Self-Hosted SigNoz** - no OAuth step is needed unless the server runs with `OAUTH_ENABLED=true`.

### Antigravity CLI

1. Install the plugin directly from the repository. Antigravity stages the repo root as a native plugin and registers the `signoz` MCP server and its skills automatically:

   ```
   agy plugin install https://github.com/SigNoz/agent-skills
   agy plugin list   # confirm signoz is loaded
   ```

   Reinstall with the same command to update.

2. The plugin defaults to the SigNoz Cloud `us` endpoint (`https://mcp.us.signoz.cloud/mcp`). To point it at a different region or a self-hosted instance, run the setup skill in the `agy` prompt with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL (ex: `http://localhost:8000/mcp`):

   ```
   /signoz:signoz-mcp-setup <region-or-mcp-url>
   ```

   This rewrites `serverUrl` in the installed `mcp_config.json`. SigNoz Cloud `us` users can skip this step.

3. Authenticate. In the `agy` prompt, type `/mcp`, select the `signoz` server, and choose **Authenticate** to start the OAuth flow, then complete it in the browser. Self-hosted endpoints need no OAuth unless the server runs with `OAUTH_ENABLED=true`.

### Grok Build

1. Add the marketplace and install the plugin. `--trust` is required for the bundled MCP server and hooks to activate - without it the skills load but the `signoz` server stays inactive:

   ```
   grok plugin marketplace add SigNoz/agent-skills
   grok plugin install signoz --trust
   ```

   To skip the marketplace source, install the plugin subdirectory directly with `grok plugin install SigNoz/agent-skills#plugins/signoz --trust`.

2. The plugin defaults to the SigNoz Cloud `us` endpoint (`https://mcp.us.signoz.cloud/mcp`), so `us` users can skip this step. To point it at a different region or a self-hosted instance, add the endpoint to Grok's own config with your SigNoz Cloud region (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL (ex: `http://localhost:8000/mcp`):

   ```
   grok mcp add signoz -t http https://mcp.<region>.signoz.cloud/mcp -s user
   ```

   A `[mcp_servers.signoz]` entry replaces the plugin's own registration rather than adding a second server, and unlike the bundled file it survives plugin updates. Use `-s project` to write `./.grok/config.toml` and share the endpoint with everyone working in that directory. You can also run `/signoz-mcp-setup <region-or-mcp-url>` in a Grok session and let the setup skill do it.

3. Authenticate. Run `/mcps` to open the MCP Servers modal, press `r` to refresh the list, select the `signoz` server, and press `i` to start the OAuth flow, then complete it in the browser. Self-hosted endpoints need no OAuth unless the server runs with `OAUTH_ENABLED=true`. Verify with `grok mcp doctor signoz`.

To update after new releases:

```
grok plugin marketplace update
grok plugin update signoz
```

> **Note**
>
> Grok reads `~/.claude.json`, `~/.cursor/mcp.json`, and `.mcp.json` as compatibility sources. If you already have SigNoz configured in Claude Code or Cursor, Grok loads that server alongside the plugin's, leaving two servers named `signoz` pointing at different endpoints. The `[mcp_servers.signoz]` entry in step 2 outranks both and collapses them to one.

## Install individual skills

If you want only specific skills, or you use an agent without plugin support, install skill files directly with [skills.sh](https://skills.sh). This works for any compatible agent (Codex, Cursor, Gemini, OpenCode, and more).

Install all SigNoz skills:

```
npx skills add SigNoz/agent-skills
```

Install a specific skill:

```
npx skills add SigNoz/agent-skills --skill signoz-searching-docs
npx skills add SigNoz/agent-skills --skill signoz-writing-clickhouse-queries
```

> **Note**
>
> skills.sh installs the skill files only, not the bundled MCP registration. Skills that act on your data (queries, dashboards, alerts, views) need the [SigNoz MCP Server](https://signoz.io/docs/ai/signoz-mcp-server/) connected separately.

## Available Skills

The plugin ships the skills below. Your agent selects the right one automatically when it detects a matching task. Click any name to read its source `SKILL.md`.

### Setup and docs

- [signoz-mcp-setup](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-mcp-setup/SKILL.md) - Initialize or repair the SigNoz MCP server configuration for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Windsurf, Zed, Antigravity, OpenCode, or another MCP client.
- [signoz-searching-docs](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-searching-docs/SKILL.md) - SigNoz docs guidance for instrumentation, setup, querying, alerts, and APIs.

### Querying your data

- [signoz-generating-queries](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-generating-queries/SKILL.md) - Generate queries against SigNoz observability data (traces, logs, metrics).
- [signoz-writing-clickhouse-queries](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-writing-clickhouse-queries/SKILL.md) - Optimized ClickHouse queries for SigNoz OpenTelemetry traces and logs.

### Dashboards

- [signoz-creating-dashboards](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-creating-dashboards/SKILL.md) - Create a new SigNoz dashboard from a natural-language intent - import a curated template (PostgreSQL, Redis, JVM, k8s, APM, LLM, etc.) when one fits, or build a custom dashboard with metric, trace, and log panels.
- [signoz-modifying-dashboards](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-modifying-dashboards/SKILL.md) - Modify an existing SigNoz dashboard: add, remove, or edit panels, variables, queries, and layout.
- [signoz-explaining-dashboards](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-explaining-dashboards/SKILL.md) - Explain panels, queries, and layout of an existing SigNoz dashboard.

### Alerts

- [signoz-creating-alerts](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-creating-alerts/SKILL.md) - Create SigNoz alert rules for threshold breaches, error rates, latency, anomaly detection, and absent-data conditions across metrics, logs, and traces.
- [signoz-explaining-alerts](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-explaining-alerts/SKILL.md) - Explain and interpret an existing SigNoz alert rule's configuration, evaluation behavior, notification routing, and recent fire frequency.
- [signoz-investigating-alerts](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-investigating-alerts/SKILL.md) - Diagnose why a SigNoz alert fired by correlating its signal with neighbor metrics, traces, and logs around the fire window, and ranking likely causes.

### Views and workflows

- [signoz-managing-views](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-managing-views/SKILL.md) - Create, list, inspect, update, or delete SigNoz saved views for Logs, Traces, Metrics, and Cost Meter via the SigNoz MCP server.
- [signoz-setting-up-observability](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-setting-up-observability/SKILL.md) - Orchestrate the full post-ingestion observability setup for a service - SLI/SLO capture, RED/USE exploration, focused dashboards, saved views, burn-rate and absent-data alerts, and a tuning loop - sequencing the single-artifact skills into one SLO-aware workflow.

### Cost optimization

- [signoz-reducing-telemetry-cost](https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-reducing-telemetry-cost/SKILL.md) - Investigate and reduce SigNoz telemetry ingestion cost and metric cardinality across metrics, logs, and traces through the Cost Meter, with dashboard-, alert-, and Infra-page-aware reduction recommendations.

## Learn more

- [SigNoz skills on skills.sh](https://skills.sh/signoz/agent-skills) - browse available skills and install instructions.
- [GitHub repository](https://github.com/SigNoz/agent-skills) - plugin source, skill structure, and per-client setup recipes.
- [SigNoz MCP Server](https://signoz.io/docs/ai/signoz-mcp-server/) - connect and authenticate the MCP server the skills act through.
- [AI Use Cases](https://signoz.io/docs/ai/use-cases/) - real-world workflows you can run once everything is wired up.

More docs: /docs/sitemap.md