{
  "markdown": "# SigNoz Agent Skills\n\nOfficial SigNoz skills and MCP configuration for Claude Code, Codex, Cursor,\nVS Code/GitHub Copilot, Gemini CLI, Devin CLI, Grok Build, Antigravity CLI, and\nthe [skills.sh](https://skills.sh) ecosystem. The repository publishes an\n[Agent Plugins v1](https://agent-plugins.org/) package for compatible clients.\nThe MCP setup skill\nincludes client-specific recipes for VS Code/GitHub Copilot, Claude Desktop,\nGemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, and\ngeneric HTTP MCP clients.\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| [signoz-mcp-setup](plugins/signoz/skills/signoz-mcp-setup/SKILL.md) | 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. |\n| [signoz-creating-alerts](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. |\n| [signoz-explaining-alerts](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. |\n| [signoz-investigating-alerts](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. |\n| [signoz-creating-dashboards](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. |\n| [signoz-explaining-dashboards](plugins/signoz/skills/signoz-explaining-dashboards/SKILL.md) | Explain panels, queries, and layout of an existing SigNoz dashboard. |\n| [signoz-modifying-dashboards](plugins/signoz/skills/signoz-modifying-dashboards/SKILL.md) | Modify an existing SigNoz dashboard: add, remove, or edit panels, variables, queries, and layout — patching targeted changes rather than replacing the whole dashboard. |\n| [signoz-generating-queries](plugins/signoz/skills/signoz-generating-queries/SKILL.md) | Generate queries against SigNoz observability data (traces, logs, metrics). |\n| [signoz-writing-clickhouse-queries](plugins/signoz/skills/signoz-writing-clickhouse-queries/SKILL.md) | Optimized ClickHouse queries for SigNoz OpenTelemetry traces and logs. |\n| [signoz-searching-docs](plugins/signoz/skills/signoz-searching-docs/SKILL.md) | SigNoz docs guidance for instrumentation, setup, querying, alerts, and APIs. |\n| [signoz-managing-views](plugins/signoz/skills/signoz-managing-views/SKILL.md) | Create, list, inspect, update, or delete SigNoz saved Explorer views (logs, traces, metrics) via the SigNoz MCP server. |\n| [signoz-setting-up-observability](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. |\n| [signoz-reducing-telemetry-cost](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. |\n\n## Installation\n\nThe Agent Plugins v1 `mcp.json` is used by Codex and portable clients. Claude\nCode and Cursor use their client-specific MCP registration files. Claude Code\nasks for the MCP endpoint URL during install; Codex and Cursor can use\n`signoz-mcp-setup` to initialize or repair it. The setup skill accepts a SigNoz\nCloud region such as `us`, `us2`, `eu`, `eu2`, `in`, or `in2`, any hosted MCP\nURL, or a self-hosted HTTP `/mcp` endpoint. Plugin updates can reset the bundled\nCodex and Cursor registration files to the placeholder; if that happens, rerun\n`signoz-mcp-setup`. Claude Code stores its endpoint as a persisted plugin\noption, so changing it through the setup skill or **Customize** survives plugin\nupdates.\n\nThe Devin CLI plugin ships skills only — Devin's plugin system does not bundle\nMCP servers or prompt for install-time config. Run `signoz-mcp-setup` after\ninstalling to write the `signoz` MCP server into `.devin/config.json`.\n\nThe Grok Build plugin bundles an MCP registration that works out of the box on\nthe SigNoz Cloud `us` endpoint. Grok has no install-time prompt, but unlike the\nother bundled registrations it expands `${SIGNOZ_MCP_URL}`, and a\n`[mcp_servers.signoz]` entry in Grok's own config replaces the bundled server\nrather than duplicating it — so the endpoint survives plugin updates instead of\nresetting.\n\nThe skills are authored against the current SigNoz MCP server contract. If a\ntool call fails because a parameter or schema looks different from what a skill\ndescribes, update or reconfigure the SigNoz MCP server before changing the\nworkflow.\n\nSee the full setup guide in the [SigNoz MCP Server docs](https://signoz.io/docs/ai/signoz-mcp-server/).\n\n### Agent Plugins v1\n\nAgent Plugins v1 standardizes the portable package format but leaves\ndistribution and installation to individual clients. SigNoz publishes the clean\npackage from this repository's generated\n[`agent-plugin`](https://github.com/SigNoz/agent-skills/tree/agent-plugin)\nbranch. The client-specific packages below remain supported.\n\n#### VS Code / GitHub Copilot\n\n1. Run **Chat: Install Plugin From Source** from the Command Palette.\n2. Enter `https://github.com/SigNoz/agent-skills` and install `signoz` if\n   prompted.\n3. In Copilot Chat Agent mode, run\n   `/signoz:signoz-mcp-setup <region-or-mcp-url>`, then complete authentication.\n\nFor local development, build the same clean package from the compatibility\nsource tree:\n\n```sh\npython3 scripts/package_agent_plugin.py\n```\n\nThe builder refuses to overwrite an existing output directory. Before\nrebuilding, deliberately remove or rename `dist/signoz`, or pass a different\nnew output path as the command's final argument.\n\nThis creates `dist/signoz` containing only `plugin.json`, `mcp.json`, `LICENSE`,\nand immediate-child Agent Skills under `skills/`. It can be loaded locally in a\n[compatible Agent Plugins client](https://agent-plugins.org/compatible-clients)\nfor testing. The source tree at [`plugins/signoz`](plugins/signoz) intentionally\nalso contains native Claude, Codex, Cursor, and Grok files and is not itself a\nportable package.\n\nThe portable MCP registration starts at `https://not-setup/mcp`, because Agent\nPlugins v1 does not define portable install-time configuration or credential\nfields. After installing, run `signoz-mcp-setup <region-or-mcp-url>` and complete\nthe client's OAuth flow for SigNoz Cloud. Portable non-loopback endpoints must\nuse HTTPS; for a self-hosted HTTP endpoint on another host, the skill configures\nthe named client's native MCP surface instead.\n\n### Claude Code\n\n```sh\n/plugin marketplace add SigNoz/agent-skills\n/plugin install signoz@signoz-skills\n```\n\nOn install, Claude Code prompts for your **SigNoz MCP endpoint**. For SigNoz\nCloud, keep the default `https://mcp.us.signoz.cloud/mcp` or edit the region\nsegment to your region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`). Find your\nregion under **Settings -> Ingestion** in SigNoz, or see the\n[region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/). For a\nself-hosted SigNoz, enter your own HTTP `/mcp` URL, for example\n`http://localhost:8000/mcp`.\n\nThen run `/mcp`, select the `signoz` plugin's `mcp` server, and complete the\nauthentication flow if prompted. To change the endpoint later, reconfigure the\nplugin's options or run `signoz-mcp-setup` with the new region or MCP URL.\n\nUpdate:\n\n```sh\n/plugin marketplace update\n/plugin update signoz@signoz-skills\n```\n\n> 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.\n\n### Codex\n\n```sh\ncodex plugin marketplace add SigNoz/agent-skills\n```\n\nThen, in a Codex session started from your project:\n\n1. Run `/plugins`, open the `SigNoz` marketplace, and install `signoz`.\n2. Run `signoz-mcp-setup <region>` with your SigNoz Cloud region (`us`, `us2`,\n   `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL. This rewrites the\n   bundled `mcp.json` placeholder when the endpoint is valid for Agent Plugins.\n   Non-loopback plain-HTTP endpoints cannot be stored there; for those, the\n   skill leaves `mcp.json` unchanged and configures the same `signoz` server\n   through native `codex mcp add` instead.\n3. For SigNoz Cloud, or a self-hosted MCP server explicitly configured with\n   OAuth, authenticate the MCP server:\n\n   ```sh\n   codex mcp login signoz\n   ```\n\n   Complete the browser flow with your SigNoz instance URL and a service account\n   API key. For an ordinary self-hosted endpoint without OAuth enabled, skip\n   this step and continue to verification.\n4. Verify the connection:\n\n   ```sh\n   codex mcp list   # signoz -> enabled, Auth = logged in\n   ```\n\n   or run `/mcp` in a session, then call any `signoz_*` tool. Restart Codex if\n   the `signoz` server does not appear.\n\nThe bundled `mcp.json` lives inside Codex's versioned plugin cache, so plugin\nupdates reinstall that file from this repository and can reset it to the\nplaceholder. If you want the endpoint to persist across plugin updates, also\nadd a native Codex MCP entry after resolving the endpoint:\n\n```sh\ncodex mcp add signoz --url http://localhost:8000/mcp\n```\n\nReplace the URL with your SigNoz Cloud MCP URL or self-hosted HTTP `/mcp`\nendpoint. Verify with `codex mcp get signoz`.\n\nThe Agent Plugins manifest registers the root `mcp.json` for Codex, so normal\nplugin installs do not need a separate native Codex MCP entry. To use in another\nrepo, copy `plugins/signoz` into the target repo's `plugins/` directory, add a\nmarketplace entry in `$REPO_ROOT/.agents/plugins/marketplace.json`, and repeat\nthe setup step for that workspace.\n\n### Cursor\n\nNot yet on the public Cursor Marketplace. Install via a Team Marketplace:\n\n1. Add `https://github.com/SigNoz/agent-skills` as a team marketplace in `Settings -> Plugins`.\n2. Install the `signoz` plugin from the marketplace panel.\n\nOn install, Cursor prompts for your **SigNoz Region**. The picker offers the\nSigNoz Cloud regions (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) plus a\n**`self-hosted`** option:\n\n- **SigNoz Cloud** — select your region. The bundled MCP config fills it into\n  `https://mcp.<region>.signoz.cloud/mcp` and Cursor starts the OAuth login.\n  Find your region under **Settings -> Ingestion** in SigNoz, or see the\n  [region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/).\n- **Self-hosted** — choose `self-hosted`. This skips the Cloud OAuth and leaves\n  the MCP endpoint unconfigured. After install you **must** run\n  `/signoz-mcp-setup` with your own HTTP `/mcp` URL (next step) to point Cursor\n  at your instance.\n\n3. **Self-hosted only:** run `/signoz-mcp-setup` in an agent chat with your\n   self-hosted HTTP MCP URL (for example `/signoz-mcp-setup http://localhost:8000/mcp`).\n   This updates the bundled `.signoz_cursor_mcp.json` placeholder used by the\n   Cursor plugin. (SigNoz Cloud users can skip this — the region picker already\n   configured the endpoint.)\n4. Reload Cursor, then open MCP settings and complete authentication for the\n   `signoz` server if prompted.\n\nIf you picked the wrong region or need to change a self-hosted HTTP MCP\nendpoint, run `/signoz-mcp-setup` again with the correct region or URL and\nreload Cursor.\n\n### Gemini CLI\n\n```sh\ngemini extensions install https://github.com/SigNoz/agent-skills\n```\n\nWhen prompted for the **SigNoz MCP endpoint**, enter:\n\n- **SigNoz Cloud:** `https://mcp.<region>.signoz.cloud/mcp` — replace `<region>` with\n  your region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`). The default is the `us`\n  Cloud endpoint.\n- **Self-hosted SigNoz:** your own `/mcp` URL, for example `http://localhost:8000/mcp`.\n\nThen authenticate:\n\n```\n/mcp auth signoz\n```\n\nFollow the prompts to enter your SigNoz instance URL and API key.\n\n### Devin CLI\n\n```sh\ndevin plugins install SigNoz/agent-skills\n```\n\nThis installs at user level and works across all projects. Devin's plugin\nsystem does not support bundled MCP servers or install-time config prompts, so\nrun `/signoz:signoz-mcp-setup` (Devin namespaces plugin skills as\n`/<plugin>:<skill>`) in a Devin session afterward with your SigNoz Cloud\nregion (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL.\nThis writes a `signoz` entry into the highest-precedence Devin config scope\nthat already has one, or `~/.config/devin/config.json` by default.\n\nFor SigNoz Cloud, start a new session and run `devin mcp login signoz` to\ncomplete OAuth. For self-hosted SigNoz, no OAuth step is needed unless the\nserver runs with `OAUTH_ENABLED=true`.\n\n### Grok Build\n\n```sh\ngrok plugin marketplace add SigNoz/agent-skills\ngrok plugin install signoz --trust\n```\n\n`--trust` is required for the bundled MCP server and hooks to activate; without\nit the skills load but the `signoz` server stays inactive. To skip the\nmarketplace source, install the plugin subdirectory directly with\n`grok plugin install SigNoz/agent-skills#plugins/signoz --trust`.\n\nThe plugin registers the `signoz` MCP server against the SigNoz Cloud `us`\nendpoint by default, so `us` users need no further configuration.\n\n**Set the endpoint.** For any other region, or for self-hosted SigNoz:\n\n```sh\ngrok mcp add signoz -t http https://mcp.<region>.signoz.cloud/mcp -s user\n```\n\nReplace `<region>` with `us`, `us2`, `eu`, `eu2`, `in`, or `in2`. Find your\nregion under **Settings -> Ingestion** in SigNoz, or see the\n[region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/). For\nself-hosted SigNoz, pass your own HTTP `/mcp` URL, for example\n`http://localhost:8000/mcp`. You can also run `/signoz-mcp-setup <region>` in a\nGrok session and let the skill do it.\n\nUse `-s user` to write `~/.grok/config.toml` (per machine, the default) or\n`-s project` to commit the endpoint to `./.grok/config.toml` for the whole team.\nRe-running the command updates the entry in place, so switching regions later is\nthe same command again. A `[mcp_servers.signoz]` entry **replaces** the\nplugin-provided server of the same name, so you always end up with exactly one\n`signoz` server rather than a duplicate. For a one-off or CI run, skip config\nentirely and export `SIGNOZ_MCP_URL` instead — the bundled registration reads it.\n\n**Authenticate (SigNoz Cloud).** Run `/mcps` (or press Ctrl+L and open the MCP\nServers tab), press `r` to reload after a config change, then select `signoz`\nand press `i` to start the OAuth flow. Self-hosted endpoints need no OAuth\nunless the server runs with `OAUTH_ENABLED=true`. Verify with\n`grok mcp doctor signoz`, which should report `1 healthy`.\n\nUpdate:\n\n```sh\ngrok plugin marketplace update\ngrok plugin update signoz\n```\n\n> **Already using SigNoz in Claude Code or Cursor?** Grok also reads\n> `~/.claude.json`, `~/.cursor/mcp.json`, and `.mcp.json` as compatibility\n> sources. If one of them already defines a `signoz` server, Grok loads it\n> *alongside* the plugin's — two live servers with the same name pointing at\n> different endpoints, which `grok mcp doctor` reports as two. Setting\n> `[mcp_servers.signoz]` with the `grok mcp add` command above outranks both\n> and collapses them to one.\n\n### Antigravity CLI\n\nInstall directly from this repository — Antigravity CLI stages the repo root as\na native plugin (`plugin.json` + `mcp_config.json` + `skills/`):\n\n```sh\nagy plugin install https://github.com/SigNoz/agent-skills\nagy plugin list   # confirm signoz is loaded\n```\n\nReinstall with the same command to update. Antigravity registers the `signoz`\nMCP server (default SigNoz Cloud `us` endpoint, `https://mcp.us.signoz.cloud/mcp`)\nand the SigNoz skills automatically. The installed plugin is staged at\n`~/.gemini/antigravity-cli/plugins/signoz/`.\n\n**Authenticate (SigNoz Cloud).** In the `agy` prompt, type `/mcp`, select the\n`signoz` server, and choose **Authenticate** to start the OAuth flow. Complete\nit in the browser (over SSH, `agy` prints an authorization URL to paste in and a\ncode to paste back). Self-hosted endpoints need no OAuth unless the server runs\nwith `OAUTH_ENABLED=true`.\n\n**Change the endpoint.** In the `agy` prompt, run the setup skill with your\ntarget — a SigNoz Cloud region or a self-hosted MCP URL:\n\n```\n/signoz:signoz-mcp-setup <region>        # e.g. us, us2, eu, eu2, in, in2\n/signoz:signoz-mcp-setup <mcp-url>       # e.g. http://localhost:8000/mcp\n```\n\nThis rewrites `serverUrl` in the installed `mcp_config.json`. Then run `/mcp` to\nreload and re-authenticate (self-hosted needs no OAuth unless the server runs\nwith `OAUTH_ENABLED=true`). You can also edit the `serverUrl` value directly.\n\n### Other MCP Clients\n\nThe setup skill includes native config recipes for VS Code/GitHub Copilot,\nClaude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity\nCLI, OpenCode, and generic HTTP MCP clients. These clients do not all consume this plugin\nautomatically; install or copy the skill where your client supports skills, or\nuse the client-specific setup snippets in the skill as a reference.\n\nFor SigNoz Cloud, prefer the hosted MCP URL and client OAuth flow. For\nself-hosted SigNoz, the skill supports HTTP `/mcp` endpoints and stdio\nlocal-binary recipes. It avoids writing API keys into tracked project files.\n\n### skills.sh\n\n```sh\nnpx skills add SigNoz/agent-skills                                   # all skills\nnpx skills add SigNoz/agent-skills --skill signoz-searching-docs                # specific skill\nnpx skills add SigNoz/agent-skills --skill signoz-writing-clickhouse-queries    # specific skill\n```\n\n## Repository Structure\n\n```text\n.\n├── .agents/plugins/marketplace.json        # Codex marketplace\n├── .claude-plugin/marketplace.json         # Claude Code marketplace\n├── .cursor-plugin/marketplace.json         # Cursor marketplace\n├── .grok-plugin/marketplace.json           # Grok Build marketplace\n├── .devin-plugin/plugin.json               # Devin CLI plugin manifest\n├── .github/workflows/\n│   ├── auto-version-bump.yml               # Follow-up version PR automation\n│   ├── publish-agent-plugin.yml             # Publishes the generated agent-plugin branch\n│   └── validate-agent-plugin.yml           # Portable schema and skill checks\n├── gemini-extension.json                   # Gemini CLI extension manifest\n├── plugin.json                             # Antigravity plugin manifest (native, repo root)\n├── mcp_config.json                         # Antigravity MCP config (serverUrl)\n├── scripts/package_agent_plugin.py         # Builds clean dist/signoz package\n├── skills -> plugins/signoz/skills         # Gemini CLI, Devin CLI & Antigravity skills (symlink)\n├── plugins/signoz/\n│   ├── plugin.json                         # Portable manifest source\n│   ├── mcp.json                            # Portable and Codex MCP config source\n│   ├── .codex-plugin/plugin.json           # Codex plugin manifest\n│   ├── .claude-plugin/plugin.json          # Claude Code plugin manifest\n│   ├── .cursor-plugin/plugin.json          # Cursor plugin manifest\n│   ├── .grok-plugin/plugin.json            # Grok Build plugin manifest\n│   ├── .signoz_claude_mcp.json             # Claude Code MCP config\n│   ├── .signoz_cursor_mcp.json             # Cursor MCP config\n│   ├── .signoz_grok_mcp.json               # Grok Build MCP config (env-interpolated)\n│   ├── hooks/                              # Auto-allow hooks\n│   └── skills/\n│       ├── signoz-mcp-setup/\n│       │   └── references/                 # Endpoint mapping and client recipes\n│       ├── signoz-creating-alerts/\n│       ├── signoz-explaining-alerts/\n│       ├── signoz-investigating-alerts/\n│       ├── signoz-writing-clickhouse-queries/\n│       ├── signoz-explaining-dashboards/\n│       ├── signoz-modifying-dashboards/\n│       ├── signoz-searching-docs/\n│       ├── signoz-generating-queries/\n│       └── signoz-managing-views/\n└── README.md\n```\n\n| ID | Value |\n|----|-------|\n| Marketplace | `signoz-skills` |\n| Plugin | `signoz` |\n| Repository | `SigNoz/agent-skills` |\n| Versioning | Client CalVer `YYYY.MM.DD`; portable/Devin SemVer `YYYY.M.<DD*100+micro>`; auto-bumped |\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 20915,
  "sha": "ffc3e06821a16eb22b61c2c7c12b0421701ba3f294e8ff8c2aa926bc67adb4d9",
  "repo_slug": "signoz/agent-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_signoz_agent_skills_signoz_4d9cacfc/readme"
}