/add-datasource

name: add-datasource
description: Use for the implementation workflow that adds gcx CLI support for a datasource type not registered in internal/datasources/providers — query client, command constructors, DatasourceProvider registration. Trigger on "add support for an unsupported datasource type" or "new datasource type". NOT for creating or configuring a datasource instance in a Grafana stack (that is the shipped `gcx datasources create`), NOT for extending an already-registered kind, and NOT for deciding the integration tier or contract or running pre-review self-checks — use the existing kind's implementation or the repo-local integrate-with-gcx contributor skill instead.

Add Datasource Type

Orchestrates adding a new datasource type plugin — from API discovery through verified implementation. Three stages, worked autonomously: the stage boundaries are checkpoints you satisfy, not approvals you wait for.

When to Use

• User wants gcx CLI support for a datasource type gcx does not yet support
• User says "add support for an unsupported datasource type", "new datasource type"
• A task references datasource type implementation

**When NOT to use**:

• **The user wants a datasource instance, not a type.** "Add a datasource" most

often means creating or configuring one in a Grafana stack — that is `gcx datasources create` / `update`, already shipped. This skill writes Go code to teach gcx a new *kind*. Confirm which one is meant before starting.

• The kind is already registered under `internal/datasources/providers/` —

extend that implementation instead of adding a duplicate.

• The product is a Grafana Cloud product, not a datasource — use

`/add-provider`.

Entry paths

**Invoked from `integrate-with-gcx`** (the placement section already exists — necessity, command path, backend evidence, wiring, readiness):

• Skip the Stage 1 questions it already answers: the datasource kind and plugin

type string, the query/metadata endpoints, and the readiness verdict. Record them and move on rather than re-asking.

• The Stage 1 approval gate **does not apply on this path**. Build autonomously.

If a query-language or endpoint detail is genuinely missing, discover it from the vendor docs, or ask one targeted question carrying the evidence and a recommendation — never fall back to a blanket approval gate.

• Start at Stage 2, and use Stage 3 verification as written.

**Invoked directly** (no placement section): work through all three stages. Autonomy is the same as above — the Stage 1 gate is a checkpoint you satisfy, not an approval you wait for. Discover the plugin type, endpoints and response shapes from `bin/gcx datasources list -o json`, the vendor's API docs and `bin/gcx api` probes; present findings and keep going. Ask only where an unresolved answer would materially change the implementation — an unknown query-expression format, an endpoint you cannot verify. If no instance is reachable, report the live checks as **UNVERIFIED** with the reason rather than blocking or claiming them green.

The flow, however you got here

contract (proportional)  →  implementation  →  Review

Both entry paths run all three, and none of them is a document or a gate:

• **Contract, before code** — `.claude/skills/integrate-with-gcx/references/contract-and-tests.md`,

sized to the change. If you arrived from `integrate-with-gcx` the contract already exists; use it, don't redo it.

• **Review, before calling it review-ready** —

`.claude/skills/integrate-with-gcx/references/self-review.md`, re-run after every fix push.

That is where the naming, typed-input, output-class, completeness, error, token-cost and test-quality guidance lives. Read those two rather than restating them here.

Workflow

Discover ───────> Implement ──gate──> Verify
   │                    │                  │
   v                    v                  v
research findings   code per step      smoke tests

| Stage | Deliverable | Gate | |-------|-------------|------| | 1. Discover | research findings | findings presented; no approval wait | | 2. Implement | Code (one step at a time) | `mise run gate` passes per step; `GCX_AGENT_MODE=false mise run all` once before push | | 3. Verify | Smoke tests + annotation check | smoke tests run or reported UNVERIFIED; wiring checks pass |

Prerequisites — discover these, don't ask for them

Settle each from the repo and the environment first. Ask only if what remains is materially insufficient, and then in one grouped question carrying the evidence and a recommendation:

• **Datasource type** — usually stated in the request. Confirm the plugin type

string yourself with `bin/gcx datasources list -o json`.

• **Access** — check for a configured context the same way. If none is reachable,

proceed against the vendor's API docs and report every live check as UNVERIFIED with the reason; do not stop.

• **Scope** — infer from the request (a "query client" means `query` first) and

state what you inferred. Extra verbs are additive later; a wrong frozen name is not.

---

Stage 1: Discover

1a. Gather User Context

1. Run `bin/gcx datasources list -o json` to find the datasource UID and plugin type string. If the user has a configured context, do this yourself rather than asking them to do it. 2. Find the query language and endpoint shapes from the vendor's API docs or the plugin's source before writing anything — do not guess them. If they cannot be settled that way, ask once, naming exactly what is missing and what you will assume otherwise. 3. Known quirks — special auth, pagination, response formats?

1b. Research

• Use `bin/gcx api` raw calls to probe the datasource proxy API surface

(`/api/datasources/proxy/uid/{uid}/...` or `/api/datasources/uid/{uid}/resources/...`)

• Identify query endpoints and response shapes from the vendor's API docs or the

plugin's source

• Identify metadata endpoints (labels, se