SigNoz Agent Skills

Official SigNoz skills and MCP configuration for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Gemini CLI, Devin CLI, Grok Build, Antigravity CLI, and the skills.sh ecosystem. The repository publishes an Agent Plugins v1 package for compatible clients. The MCP setup skill includes client-specific recipes for VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, and generic HTTP MCP clients.

Skills

Skill	Description
signoz-mcp-setup	Initialize or repair the SigNoz Agent Plugins v1 or client-specific MCP server configuration for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, or another MCP client.
signoz-creating-alerts	Create SigNoz alert rules for threshold breaches, error rates, latency, anomaly detection, and absent-data conditions across metrics, logs, and traces.
signoz-explaining-alerts	Explain and interpret an existing SigNoz alert rule's configuration, evaluation behavior, notification routing, and recent fire frequency.
signoz-investigating-alerts	Diagnose why a SigNoz alert fired by correlating its signal with neighbor metrics, traces, and logs around the fire window, and ranking likely causes.
signoz-creating-dashboards	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-explaining-dashboards	Explain panels, queries, and layout of an existing SigNoz dashboard.
signoz-modifying-dashboards	Modify an existing SigNoz dashboard: add, remove, or edit panels, variables, queries, and layout — patching targeted changes rather than replacing the whole dashboard.
signoz-generating-queries	Generate queries against SigNoz observability data (traces, logs, metrics).
signoz-writing-clickhouse-queries	Optimized ClickHouse queries for SigNoz OpenTelemetry traces and logs.
signoz-searching-docs	SigNoz docs guidance for instrumentation, setup, querying, alerts, and APIs.
signoz-managing-views	Create, list, inspect, update, or delete SigNoz saved Explorer views (logs, traces, metrics) via the SigNoz MCP server.
signoz-setting-up-observability	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.
signoz-reducing-telemetry-cost	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.

Installation

The Agent Plugins v1 mcp.json is used by Codex and portable clients. Claude Code and Cursor use their client-specific MCP registration files. Claude Code asks for the MCP endpoint URL during install; Codex and Cursor can use signoz-mcp-setup to initialize or repair it. The setup skill accepts a SigNoz Cloud region such as us, us2, eu, eu2, in, or in2, any hosted MCP URL, or a self-hosted HTTP /mcp endpoint. Plugin updates can reset the bundled Codex and Cursor registration files to the placeholder; if that happens, rerun signoz-mcp-setup. Claude Code stores its endpoint as a persisted plugin option, so changing it through the setup skill or Customize survives plugin updates.

The Devin CLI plugin ships skills only — Devin's plugin system does not bundle MCP servers or prompt for install-time config. Run signoz-mcp-setup after installing to write the signoz MCP server into .devin/config.json.

The Grok Build plugin bundles an MCP registration that works out of the box on the SigNoz Cloud us endpoint. Grok has no install-time prompt, but unlike the other bundled registrations it expands ${SIGNOZ_MCP_URL}, and a [mcp_servers.signoz] entry in Grok's own config replaces the bundled server rather than duplicating it — so the endpoint survives plugin updates instead of resetting.

The skills are authored against the current SigNoz MCP server contract. If a tool call fails because a parameter or schema looks different from what a skill describes, update or reconfigure the SigNoz MCP server before changing the workflow.

See the full setup guide in the SigNoz MCP Server docs.

Agent Plugins v1

Agent Plugins v1 standardizes the portable package format but leaves distribution and installation to individual clients. SigNoz publishes the clean package from this repository's generated agent-plugin branch. The client-specific packages below remain supported.

VS Code / GitHub Copilot

1. Run Chat: Install Plugin From Source from the Command Palette.
2. Enter https://github.com/SigNoz/agent-skills and install signoz if prompted.
3. In Copilot Chat Agent mode, run /signoz:signoz-mcp-setup <region-or-mcp-url>, then complete authentication.

For local development, build the same clean package from the compatibility source tree:

python3 scripts/package_agent_plugin.py

The builder refuses to overwrite an existing output directory. Before rebuilding, deliberately remove or rename dist/signoz, or pass a different new output path as the command's final argument.

This creates dist/signoz containing only plugin.json, mcp.json, LICENSE, and immediate-child Agent Skills under skills/. It can be loaded locally in a compatible Agent Plugins client for testing. The source tree at plugins/signoz intentionally also contains native Claude, Codex, Cursor, and Grok files and is not itself a portable package.

The portable MCP registration starts at https://not-setup/mcp, because Agent Plugins v1 does not define portable install-time configuration or credential fields. After installing, run signoz-mcp-setup <region-or-mcp-url> and complete the client's OAuth flow for SigNoz Cloud. Portable non-loopback endpoints must use HTTPS; for a self-hosted HTTP endpoint on another host, the skill configures the named client's native MCP surface instead.

Claude Code

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

On install, Claude Code prompts for your SigNoz MCP endpoint. For SigNoz Cloud, keep the default https://mcp.us.signoz.cloud/mcp or edit the region segment to your region (us, us2, eu, eu2, in, or in2). Find your region under Settings -> Ingestion in SigNoz, or see the region reference. For a self-hosted SigNoz, enter your own HTTP /mcp URL, for example http://localhost:8000/mcp.

Then run /mcp, select the signoz plugin's mcp 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.

Update:

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

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

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. Run signoz-mcp-setup <region> with your SigNoz Cloud region (us, us2, eu, eu2, in, in2) or a self-hosted HTTP MCP URL. This rewrites the bundled mcp.json placeholder when the endpoint is valid for Agent Plugins. Non-loopback plain-HTTP endpoints cannot be stored there; for those, the skill leaves mcp.json unchanged and configures the same signoz server through native codex mcp add instead.

3. For SigNoz Cloud, or a self-hosted MCP server explicitly configured with OAuth, authenticate the MCP server:

   codex mcp login signoz

   Complete the browser flow with your SigNoz instance URL and a service account API key. For an ordinary self-hosted endpoint without OAuth enabled, skip this step and continue to verification.

4. Verify the connection:

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

   or run /mcp in a session, then call any signoz_* tool. Restart Codex if the signoz server does not appear.

The bundled mcp.json lives inside Codex's versioned plugin cache, so plugin updates reinstall that file from this repository and can reset it to the placeholder. If you want the endpoint to persist across plugin updates, also add a native Codex MCP entry after resolving the endpoint:

codex mcp add signoz --url http://localhost:8000/mcp

Replace the URL with your SigNoz Cloud MCP URL or self-hosted HTTP /mcp endpoint. Verify with codex mcp get signoz.

The Agent Plugins manifest registers the root mcp.json for Codex, so normal plugin installs do not need a separate native Codex MCP entry. To use in another repo, copy plugins/signoz into the target repo's plugins/ directory, add a marketplace entry in $REPO_ROOT/.agents/plugins/marketplace.json, and repeat the setup step for that workspace.

Cursor

Not yet on the public Cursor Marketplace. Install via a Team Marketplace:

1. Add https://github.com/SigNoz/agent-skills as a team marketplace in Settings -> Plugins.
2. Install the signoz plugin from the marketplace panel.

On install, Cursor prompts for your SigNoz Region. The picker offers the SigNoz Cloud regions (us, us2, eu, eu2, in, in2) plus a self-hosted option:

• SigNoz Cloud — select your region. The bundled MCP config fills it into https://mcp.<region>.signoz.cloud/mcp and Cursor starts the OAuth login. Find your region under Settings -> Ingestion in SigNoz, or see the region reference.
• Self-hosted — choose self-hosted. This skips the Cloud OAuth and leaves the MCP endpoint unconfigured. After install you must run /signoz-mcp-setup with your own HTTP /mcp URL (next step) to point Cursor at your instance.

3. Self-hosted only: run /signoz-mcp-setup in an agent chat with your self-hosted HTTP MCP URL (for example /signoz-mcp-setup http://localhost:8000/mcp). This updates the bundled .signoz_cursor_mcp.json placeholder used by the Cursor plugin. (SigNoz Cloud users can skip this — the region picker already configured the endpoint.)
4. Reload Cursor, then open MCP settings and complete authentication for the signoz server if prompted.

If you picked the wrong region or need to change a self-hosted HTTP MCP endpoint, run /signoz-mcp-setup again with the correct region or URL and reload Cursor.

Gemini CLI

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

When prompted for the SigNoz MCP endpoint, enter:

• SigNoz Cloud: https://mcp.<region>.signoz.cloud/mcp — replace <region> with your region (us, us2, eu, eu2, in, or in2). The default is the us Cloud endpoint.
• Self-hosted SigNoz: your own /mcp 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

devin plugins install SigNoz/agent-skills

This installs at user level and works across all projects. Devin's plugin system does not support bundled MCP servers or install-time config prompts, so run /signoz:signoz-mcp-setup (Devin namespaces plugin skills as /<plugin>:<skill>) in a Devin session afterward with your SigNoz Cloud region (us, us2, eu, eu2, in, in2) or a self-hosted HTTP 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.

For SigNoz Cloud, start a new session and run devin mcp login signoz to complete OAuth. For self-hosted SigNoz, no OAuth step is needed unless the server runs with OAUTH_ENABLED=true.

Grok Build

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

--trust is required for the bundled MCP server and hooks to activate; without it the skills load but the signoz server stays inactive. To skip the marketplace source, install the plugin subdirectory directly with grok plugin install SigNoz/agent-skills#plugins/signoz --trust.

The plugin registers the signoz MCP server against the SigNoz Cloud us endpoint by default, so us users need no further configuration.

Set the endpoint. For any other region, or for self-hosted SigNoz:

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

Replace <region> with us, us2, eu, eu2, in, or in2. Find your region under Settings -> Ingestion in SigNoz, or see the region reference. For self-hosted SigNoz, pass your own HTTP /mcp URL, for example http://localhost:8000/mcp. You can also run /signoz-mcp-setup <region> in a Grok session and let the skill do it.

Use -s user to write ~/.grok/config.toml (per machine, the default) or -s project to commit the endpoint to ./.grok/config.toml for the whole team. Re-running the command updates the entry in place, so switching regions later is the same command again. A [mcp_servers.signoz] entry replaces the plugin-provided server of the same name, so you always end up with exactly one signoz server rather than a duplicate. For a one-off or CI run, skip config entirely and export SIGNOZ_MCP_URL instead — the bundled registration reads it.

Authenticate (SigNoz Cloud). Run /mcps (or press Ctrl+L and open the MCP Servers tab), press r to reload after a config change, then select signoz and press i to start the OAuth flow. Self-hosted endpoints need no OAuth unless the server runs with OAUTH_ENABLED=true. Verify with grok mcp doctor signoz, which should report 1 healthy.

Update:

grok plugin marketplace update
grok plugin update signoz

Already using SigNoz in Claude Code or Cursor? Grok also reads ~/.claude.json, ~/.cursor/mcp.json, and .mcp.json as compatibility sources. If one of them already defines a signoz server, Grok loads it alongside the plugin's — two live servers with the same name pointing at different endpoints, which grok mcp doctor reports as two. Setting [mcp_servers.signoz] with the grok mcp add command above outranks both and collapses them to one.

Antigravity CLI

Install directly from this repository — Antigravity CLI stages the repo root as a native plugin (plugin.json + mcp_config.json + skills/):

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

Reinstall with the same command to update. Antigravity registers the signoz MCP server (default SigNoz Cloud us endpoint, https://mcp.us.signoz.cloud/mcp) and the SigNoz skills automatically. The installed plugin is staged at ~/.gemini/antigravity-cli/plugins/signoz/.

Authenticate (SigNoz Cloud). In the agy prompt, type /mcp, select the signoz server, and choose Authenticate to start the OAuth flow. Complete it in the browser (over SSH, agy prints an authorization URL to paste in and a code to paste back). Self-hosted endpoints need no OAuth unless the server runs with OAUTH_ENABLED=true.

Change the endpoint. In the agy prompt, run the setup skill with your target — a SigNoz Cloud region or a self-hosted MCP URL:

/signoz:signoz-mcp-setup <region>        # e.g. us, us2, eu, eu2, in, in2
/signoz:signoz-mcp-setup <mcp-url>       # e.g. http://localhost:8000/mcp

This rewrites serverUrl in the installed mcp_config.json. Then run /mcp to reload and re-authenticate (self-hosted needs no OAuth unless the server runs with OAUTH_ENABLED=true). You can also edit the serverUrl value directly.

Other MCP Clients

The setup skill includes native config recipes for VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, and generic HTTP MCP clients. These clients do not all consume this plugin automatically; install or copy the skill where your client supports skills, or use the client-specific setup snippets in the skill as a reference.

For SigNoz Cloud, prefer the hosted MCP URL and client OAuth flow. For self-hosted SigNoz, the skill supports HTTP /mcp endpoints and stdio local-binary recipes. It avoids writing API keys into tracked project files.

skills.sh

npx skills add SigNoz/agent-skills                                   # all skills
npx skills add SigNoz/agent-skills --skill signoz-searching-docs                # specific skill
npx skills add SigNoz/agent-skills --skill signoz-writing-clickhouse-queries    # specific skill

Repository Structure

.
├── .agents/plugins/marketplace.json        # Codex marketplace
├── .claude-plugin/marketplace.json         # Claude Code marketplace
├── .cursor-plugin/marketplace.json         # Cursor marketplace
├── .grok-plugin/marketplace.json           # Grok Build marketplace
├── .devin-plugin/plugin.json               # Devin CLI plugin manifest
├── .github/workflows/
│   ├── auto-version-bump.yml               # Follow-up version PR automation
│   ├── publish-agent-plugin.yml             # Publishes the generated agent-plugin branch
│   └── validate-agent-plugin.yml           # Portable schema and skill checks
├── gemini-extension.json                   # Gemini CLI extension manifest
├── plugin.json                             # Antigravity plugin manifest (native, repo root)
├── mcp_config.json                         # Antigravity MCP config (serverUrl)
├── scripts/package_agent_plugin.py         # Builds clean dist/signoz package
├── skills -> plugins/signoz/skills         # Gemini CLI, Devin CLI & Antigravity skills (symlink)
├── plugins/signoz/
│   ├── plugin.json                         # Portable manifest source
│   ├── mcp.json                            # Portable and Codex MCP config source
│   ├── .codex-plugin/plugin.json           # Codex plugin manifest
│   ├── .claude-plugin/plugin.json          # Claude Code plugin manifest
│   ├── .cursor-plugin/plugin.json          # Cursor plugin manifest
│   ├── .grok-plugin/plugin.json            # Grok Build plugin manifest
│   ├── .signoz_claude_mcp.json             # Claude Code MCP config
│   ├── .signoz_cursor_mcp.json             # Cursor MCP config
│   ├── .signoz_grok_mcp.json               # Grok Build MCP config (env-interpolated)
│   ├── hooks/                              # Auto-allow hooks
│   └── skills/
│       ├── signoz-mcp-setup/
│       │   └── references/                 # Endpoint mapping and client recipes
│       ├── signoz-creating-alerts/
│       ├── signoz-explaining-alerts/
│       ├── signoz-investigating-alerts/
│       ├── signoz-writing-clickhouse-queries/
│       ├── signoz-explaining-dashboards/
│       ├── signoz-modifying-dashboards/
│       ├── signoz-searching-docs/
│       ├── signoz-generating-queries/
│       └── signoz-managing-views/
└── README.md

ID	Value
Marketplace	signoz-skills
Plugin	signoz
Repository	SigNoz/agent-skills
Versioning	Client CalVer YYYY.MM.DD; portable/Devin SemVer YYYY.M.<DD*100+micro>; auto-bumped

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.