How to use the Metric Diagnostics agent skill

What the skill makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches its description. This one covers metric movements, anomalies, gaps and discrepancies. When triggered, the agent follows a structured investigation rather than offering a quick explanation.

The workflow confirms the metric definition and data source, measures the size and timing of the change, breaks the change down by likely drivers, and checks whether those drivers really explain it. It ends by stating what is verified, what is only likely, what remains unresolved, and what to check next. It also points to related skills for business context, data quality checks, or recommendations.

Install the skill from the ZIP download

Download the ZIP for the metric-diagnostics skill from this page and unzip it. The skill is made of two files, agents/openai.yaml and SKILL.md, so the unzipped folder should contain them.

For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it is available only there.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Give the agent access to your data

This skill is only useful if the agent can query the sources that hold your metric. The skill requires access to the data sources the agent will query, such as databases, warehouse tables, semantic layers, or dashboards. This access is typically provided through connected tools or through data you supply.

The skill is designed to stop and ask for a required source rather than guess. If the agent cannot reach the source of truth for your metric, expect it to request that source instead of producing a conclusion.

Trigger the skill with natural requests

You do not need a special command. Describe the problem in plain language, naming the metric and the comparison you care about. The skill's description covers requests about the drivers of a movement, anomaly, gap, or discrepancy, so phrase your request around one of those.

Good requests state the metric, the period and what surprised you. You can also name the skill directly with $metric-diagnostics where your tool supports that reference style.

• Why did weekly active users drop 12% last week compared with the previous four-week average?
• Our finance dashboard and the warehouse report disagree on revenue for March. Find out why.
• Conversion rose sharply on Tuesday. What is driving it?
• Which segments explain the gap between the two churn numbers?

What the agent does during an investigation

The skill works through a sequence. It first defines the diagnostic question, including what the metric means, the time window and comparison, the population and grain, and which source owns the definition. It then validates the metric definition and checks freshness and lineage before explaining anything.

Next it quantifies the pattern itself, then chooses the smallest set of cuts likely to explain it. It sizes the main drivers, checks whether they hold under the right comparison, and treats measurement problems such as logging changes, incomplete recent data, duplicated rows or a shifted denominator as possible explanations in their own right.

Finally it reports in four groups: verified, likely, unresolved, and useful next steps. This structure makes it clear which parts of the answer you can rely on.

Choose the right kind of question

The skill handles several question types differently. A metric change compares a focal window with a baseline and tests mix shift against within-segment movement. A spike or incident looks at onset, peak, recovery and affected slices. A concentration question ranks contributors and looks for movers, entrants and exits. A reconciliation question aligns definitions, filters, grain and exclusions, then quantifies the components of the gap and any residual.

Naming the type of question in your request, such as 'reconcile these two reports', helps the agent pick the right frame.

Know the limits and safety notes

According to the skill's listing, it does not run scripts and does not use the network. Its own actions are limited to reasoning over the data sources you have connected or provided.

The skill does not make business decisions on its own. It explains movements, but human judgement is still needed for recommendations. If you ask for a tradeoff or recommendation, the skill points you to the product-business-analysis skill for that part.

It optionally references other skills: gather-business-context, analyze-data-quality, product-business-analysis and jupyter-notebooks. These are only used when they are available and relevant.

• Runs scripts: no
• Uses network: no
• Recommendations are left to human judgement