ai-analyst-lab/ai-analyst-plugin/metrics

Skill: Metrics

Purpose

Browse, search, and display metric definitions from the active dataset's metric dictionary. Provides quick access to how metrics are defined, computed, and validated.

When to Use

• User says /metrics or "show me the metrics" or "what metrics do we track?"
• During analysis, to confirm a metric's definition before computing it
• When writing a metric spec, to check for existing definitions

Deference rule: metric-shaped meaning questions ("what does ARR mean here?", "how is churn defined?") come here first; if the metric is not in the dictionary and the term looks organizational (a product, team, or general glossary term), hand off to the business skill before suggesting metric-spec.

Invocation

/metrics — list all metrics for the active dataset /metrics {id} — show full spec for a specific metric /metrics category={cat} — filter by category (e.g., monetization) /metrics search={term} — search metric names and descriptions

Instructions

Step 1: Load Metric Dictionary

1. Read .knowledge/active.yaml to identify the active dataset.
2. Read .knowledge/datasets/{active}/metrics/index.yaml for the metric list.
3. If no metrics directory exists: "No metric dictionary for this dataset. Use the metric-spec skill to define metrics."

Step 2: Execute Command

List all (`/metrics`):

• Display as a table: id, name, category, direction, validation_status
• Group by category
• Show total count
• If dictionary is empty AND user mentions specific analysis context (e.g., "revenue analysis", "conversion analysis"):
• Read .knowledge/datasets/{active}/schema.md to explore available tables/columns
• Suggest 3-5 relevant metrics the user could define for their analysis context
• Include suggested SQL formulas for each
• Reference the metric-spec skill for formalization

Show specific (`/metrics {id}`):

• Read .knowledge/datasets/{active}/metrics/{id}.yaml
• Display: name, category, owner, full definition (formula, unit, direction, granularity), source tables, dimensions, guardrails, typical range, validation status
• If metric not found:
• Suggest closest match from index (fuzzy string match on name)
• Fallback search strategy: Search working/, outputs/, and .knowledge/analyses/ for recent usage of the metric name
• If found in recent work, extract the formula/definition used and offer to formalize it
• If not found anywhere, suggest defining it via metric-spec skill

Filter by category (`/metrics category=monetization`):

• Filter index by category field
• Display filtered table
• If no matches: list available categories and suggest closest match

Search (`/metrics search=revenue`):

• Search metric names and descriptions (case-insensitive substring)
• Display matching metrics
• If no matches found:
• Don't just say "not found" — be proactive
• Read .knowledge/datasets/{active}/schema.md to explore tables/columns
• Identify columns related to the search term (e.g., "revenue" → find total_amount, revenue, sales columns)
• Suggest 3-5 metrics the user could define based on available data
• Include table.column references and suggested formulas
• Offer to define the metric via metric-spec skill

Step 3: Contextual Suggestions

After displaying metrics, suggest relevant actions:

• "Want to validate {metric} against the current data? Use the data-profiling skill."
• "Need to define a new metric? Use the metric-spec skill."
• "Want to see how {metric} trends over time? Ask me to analyze it."

Edge Cases

• No active dataset: Prompt to connect one via /connect-data
• Empty metric dictionary: Suggest using metric-spec skill. If user mentioned specific analysis context (revenue, conversion, engagement), proactively suggest relevant metrics to define.
• Metric referenced but not in dictionary: Search recent work for usage, extract definition if found, offer to formalize it.
• Stale validation: Flag metrics where last_validated is >30 days ago
• Search returns no results: Explore schema and suggest metrics related to the search term rather than just reporting "not found"

Why These Guidelines Matter

The goal is to make the metrics skill helpful in all scenarios — even when the dictionary is empty or search fails. Users often ask about metrics before they're formally defined. Instead of dead-ending with "not found," we want to:

1. Understand user context — If they mention "revenue analysis" or search for "revenue", they're signaling what domain they care about
2. Explore available data — Read the schema to see what's actually available
3. Suggest concrete next steps — Provide specific metric candidates with formulas, not just generic advice
4. Lower friction for formalization — Make it easy to go from "I need this metric" to "this metric is now defined"

This approach turns the metrics skill from a simple dictionary lookup into an intelligent assistant that helps users build their metric dictionary organically.