How to use the Axiom Alerting agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches the skill's description. This one is named axiom-alerting and its description says it creates and manages Axiom monitors and notifiers via the v2 public API.

Once installed, the agent can set up notification destinations (notifiers) such as email, Slack, or a custom webhook. It can then build monitors that watch query results and notify those destinations when something looks wrong. The skill also guides the agent to check monitor history and adjust thresholds until alerts behave sensibly.

• Notifiers: email, Slack, or custom webhook destinations, one channel per notifier.
• Monitors: Threshold, MatchEvent, and AnomalyDetection types that run an APL or MPL query on a schedule.
• Validation: reading monitor history over a time range to see whether the alert would have fired.
• Maintenance: listing, getting, updating and deleting existing monitors and notifiers.

What do you need before installing?

You need an Axiom account and an API token. The skill's source says every operation requires one. Tokens start with the prefix xaat-. The token needs scopes for monitor and notifier management and for dataset query access.

The README lists these requirements: curl, jq, and a ~/.axiom.toml file with at least one deployment. The skill also needs a shell that can run the bundled bash scripts and network access to api.axiom.co.

• An Axiom account with an API token (xaat- prefix) and your org ID.
• Token scopes for monitor management, notifier management, and dataset query access.
• curl and jq installed.
• A shell that can run bash scripts.
• Network access to api.axiom.co.

How do you install the skill?

Download the ZIP from this page and unzip it into one of two locations. For a personal install available across projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

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

The package contains README.md and SKILL.md. SKILL.md holds the agent instructions and the README is a human-readable overview.

• Personal: ~/.claude/skills/axiom-alerting/
• Project: .claude/skills/axiom-alerting/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload

How do you configure .axiom.toml?

The skill reads Bearer token auth from .axiom.toml, looked up in the project root or in your home directory (~/.axiom.toml). Each entry under deployments is a named environment that the scripts take as their first argument. The skill's examples use a deployment called prod.

Replace the placeholder values with your own token and org ID. Keep this file private, because it contains a credential.

How do you run the setup script?

Run the setup script once from the skill folder. The README shows the path as skills/axiom-alerting/scripts/setup, so adjust the path to wherever you unzipped the skill. After setup, you can list existing notifiers and monitors to confirm your connection works.

The source does not describe what setup changes on your machine, so read scripts/setup before running it.

How do you trigger the skill with a natural request?

You do not need to name the scripts. Ask for the outcome you want, and the agent will pick the skill when your request matches its description, which covers building alerting, routing notifications, validating monitor behavior, and maintaining alert configurations. Mention Axiom and the deployment name so the agent knows which credentials to use.

A good request states the signal, the threshold or condition, the destination, and whether you want to review changes first.

• "Using the prod deployment, create a Slack notifier for #oncall and a threshold monitor that alerts when 5xx errors exceed 100 in 5 minutes."
• "List the monitors in prod and show me the history of the High Error Count monitor for the last 24 hours."
• "The disk alert in prod fires too often. Check its history and raise the threshold or trigger count until it is quieter."
• "Update the oncall email notifier to use the new address and confirm the monitors still point to it."

What does the agent do end to end?

The skill sets out a fixed workflow. The agent creates a notifier first, or reuses an existing one if it fits. It then creates or updates the monitor with notifierIds attached, checks behavior with monitor-history over a time window, and tunes threshold, rangeMinutes, intervalMinutes, and the N-of-M trigger fields. It re-checks history after each change.

The skill also lists best practices. Use one channel per notifier, use emails rather than recipients for email payloads, prefer triggerAfterNPositiveResults and triggerFromNRuns for noisy signals, and use an explicit bin() in monitor queries instead of bin_auto() for alert logic.

• Create or reuse a notifier.
• Create or update the monitor with notifierIds.
• Validate with monitor-history.
• Tune the trigger fields and re-check.

What do the monitor and notifier examples look like?

The skill includes minimal valid JSON files for each monitor type and each notifier channel. A Threshold monitor uses an operator such as Above and a threshold value. A MatchEvent monitor fires on matching events and has no operator. An AnomalyDetection monitor uses a columnName and an operator such as AboveOrBelow.

Notifier payloads put one channel inside properties. The skill shows email, Slack, and custom webhook shapes. Save an example to a JSON file and pass that file to the create script.

• Threshold, MatchEvent and AnomalyDetection are the monitor types.
• Operators are Above, Below, AboveOrEqual, BelowOrEqual and AboveOrBelow.