How to use the Query Metrics agent skill for Axiom

What is an agent skill and what does query-metrics do?

An agent skill is a folder containing a SKILL.md file of instructions, plus optional supporting files and scripts, that an AI agent such as Claude can load when a request matches the skill's description. The query-metrics skill's description says it runs metrics queries against Axiom MetricsDB through scripts, discovers metrics, tags and tag values, and is used when someone asks to query metrics, explore metric datasets, check metric values or investigate OTel metrics data.

Once installed, the agent can list metrics datasets, discover metric names, tags and tag values, and run MPL (Metrics Pipeline Language) queries. Before writing a query, the skill tells the agent to read each metric's type, temporality and unit, so it can choose suitable aggregations such as a rate for cumulative counters or quantiles for histograms.

Install the query-metrics skill

Download the ZIP of the skill from this page and unzip it into one of these locations: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a specific project to scope it to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Configure your Axiom credentials

The skill needs an Axiom account and API credentials. Create ~/.axiom.toml with your deployment, giving each deployment a name, a URL and a token. The README shows the layout with a deployment named prod pointing at https://api.axiom.co. The README.md file in the skill folder has the full setup details.

The target dataset must be of kind otel:metrics:v1. The skill also expects jq and curl to be available, and a Bash shell that can run the scripts in the scripts/ folder.

• Account: an existing Axiom account with API access
• Config file: ~/.axiom.toml with at least one deployment
• Tools: jq, curl, and a Bash shell
• Network access to Axiom endpoints

Trigger the skill with natural requests

You do not need to name scripts. Ask in plain language using the kinds of phrases in the skill description, such as asking to query metrics, explore a metric dataset, check a metric's value, or investigate OTel metrics data. The agent loads the skill and follows its workflow: list datasets, read the spec, inspect metric metadata, then run the query.

If you name a specific entity such as a service or host, the skill can search for metrics carrying that tag value. It is designed for that case rather than for general discovery of metric names.

• Show me the request latency for the frontend service over the last hour.
• What tags does my metrics dataset have?
• Check the error rate for the checkout service today.
• Which metrics mention the host web-03?

Understand how the skill picks query shapes

The skill reads each metric's type, temporality and unit before composing a query. Gauges are read directly with avg, min, max or sum, with no rate applied. Cumulative counters are converted to a per-second rate before aggregation. Delta counters are summed without a rate step. Histograms use bucket functions with quantiles rather than a plain average.

For non-monotonic counters, where values can rise and fall, the agent is instructed to ask you whether you want a rate, a delta or a current value. Results are reported with their unit, and the agent warns if you combine metrics with mismatched units.

Example queries the agent can run

Behind the scenes the agent calls scripts such as metrics-query with a deployment name, an MPL string and a time range. The skill's own examples query an HTTP server duration metric with align to $__interval using avg, filter by a service name, and group results by status code. The skill recommends using $__interval so chart resolution adapts to the zoom level.

Queries are single-quoted in the shell because MPL contains backticks, which double quotes would let the shell run as commands.

• Average HTTP server duration over the last hour for a dataset
• Filter a service and method, then group by status code over one day
• Parameterised queries using repeated -p name=value options

Safety notes: scripts and network access

This skill runs scripts and uses the network. The scripts send requests to Axiom endpoints using the token in your ~/.axiom.toml, so the skill has access to whatever that token allows. Queries can return large outputs, and grouping by a high-cardinality tag can flood the output, so the skill advises checking cardinality first.

Review the scripts in the scripts/ folder before granting access, especially if you plan to use production credentials.

• Use a token scoped to what you need where possible
• Review scripts before first use
• Prefer plain group using aggregations while exploring high-cardinality data

Tips for better results

Be specific about the service, metric or time range, since the agent can then check metadata and pick the right shape. If a result looks wrong, ask the agent to show the metric's type, temporality and unit, which often explains the problem.

Use relative times such as now-1h for quick checks, and RFC3339 timestamps for fixed windows.

• Name the dataset and deployment when you have several
• Ask for units to be shown with values
• Ask the agent to explain the MPL it wrote