An agent that knows how to query is not the same as an agent that knows your business. Out of the box it can list your Metric Blocks, run them, and build charts (see Agents, Metrics & Explore). What it doesn't know is the part that lives in your team's heads: which table is the real source for "revenue," what "active customer" means here, and the handful of gotchas that quietly produce a wrong number.

A domain-knowledge skill is how you write that down once so every answer reads from it. It is the single highest-leverage thing you can add to a workspace, because it's the difference between an answer that looks plausible and one that's actually correct.

🎯
Why it matters most. The dangerous failure isn't an obvious error, it's a clean-looking number that's quietly wrong, computed from the wrong table or the wrong definition. A domain skill is what stops that, by pinning the answer to the source and definitions your team already trust.

What a domain-knowledge skill is

It's a short document, written in plain language, that the agent reads before answering questions in that area. You keep one per domain, for example one for revenue, one for product usage, one for billing. Each lives in your workspace under Skills and shows up in the agent's index, so when someone asks a revenue question the agent pulls up the revenue knowledge first.

You don't write code. You write the things a new analyst would need to be told on their first week.

The four things to write down

1. Canonical sources, "use this, not that"

The most valuable lines you can write. For each metric, name the one real source and call out the look-alikes that will burn you.

Revenue comes from the revenue Metric Block. Do not add up the raw charges table, that's pre-refund and double-counts plan changes, so it won't match finance.

Point at a Metric Block whenever one exists, the agent will query it instead of writing SQL by hand. Name the trap tables too, so the agent recognizes them.

2. What your terms actually mean

Pin every word that could mean two things. Ambiguity is exactly where wrong-but-confident answers come from.

  • Active customer means a subscription with status active, not someone who merely logged in recently.
  • MRR is monthly recurring revenue with annual plans divided by twelve.
  • Churn is customers active at the start of the month who aren't at the end. Always report whether you mean the count or the rate.

3. The gotchas

The institutional knowledge nobody could guess from the column names.

  • Timestamps are stored in UTC, but we report in Pacific, convert before grouping by day.
  • Order status completed excludes refunds; fulfilled does not, use completed for revenue.

4. The questions it should fire on

The agent only reads a skill when the user's question matches its short description. So write the description as a magnet: pack in the words and phrasings people actually type ("revenue," "MRR," "how much are we making," "churn"). That's what pulls the right knowledge in at the right moment.

A template to start from

Copy this, rename it, and fill in your own lines. Keep it tight, a focused one-page skill beats a long one the agent skims. The block between the --- lines at the top is what the agent's index reads to decide when the skill fires, so keep that exact shape.

---
name: RevenueKnowledge
description: Canonical definitions for revenue and billing questions,
  MRR, ARR, churn, active customers, net vs gross. Read before answering
  anything about revenue or subscriptions. Names the canonical tables and
  the trap tables that won't match the dashboards.
category: Domain Knowledge
---

# Canonical sources (use this, not that)
- Revenue comes from the `revenue` Metric Block, NOT the raw charges
  table (pre-refund, double-counts plan changes).

# What the terms mean
- Active customer = subscription status `active` (not trialing).
- MRR = monthly recurring revenue, annual plans / 12.

# Gotchas
- Timestamps are UTC; we report in Pacific, convert before grouping by day.

Two ways to create one

1
Write it yourself. Go to Skills, create a new skill, and paste in the template above with your own definitions. The name, description, and category lines at the top are read automatically.
2
Let the agent help. Open a chat and say "help me write a revenue knowledge skill for this workspace." The agent walks you through the four sections, asks which tables are canonical and what your terms mean, and saves the skill for you.

Either way, the skill becomes available to the agents in your workspace, and it shows up in their index so the right one fires on the right question.

✅
Check that it fired. After you save it, ask the agent a question the skill covers and watch that it reads the skill before answering. If it doesn't, the description isn't a strong enough magnet, add the exact phrasings your team actually types.

Be specific, that's the whole point

The single rule that separates a useful domain skill from a useless one: make the rulings specific.

"Use the revenue table" helps no one. "Use the revenue Metric Block, not the raw charges table, because the latter is pre-refund and won't match finance" is the line that prevents a wrong answer next quarter. Write the specific version every time.