agentleFS
vcxcviivcxcvii/rainmaker/skills/explain-this-number/SKILL.md

explain-this-number

Skill0 starsChanged 4 months agoMITView on GitHub

Explain what a search, analytics or AI-visibility metric actually means, how it is commonly misread, and what to say instead. Reference only: it decides nothing and writes nothing, and every other Rainmaker skill cites it rather than restating a definition.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run rainmaker context --check first.

    line 26
  2. Very specific:

    Only the data/ files listed in this skill's Consumes table.

    line 34
  3. Very specific:

    If strategy.json.context_hash does not match the current hash of context/business.md, say exactly:

    line 36
  4. Very specific:

    If context/business.md carries confidence: stub, continue, and stamp every output with: "Built on a stub context.

    line 42
  5. Very specific:

    Read the entry in skills/_shared/metric-definitions.md.

    line 62
  6. Very specific:

    If the question is about the user's own number, read the relevant snapshot and quote the actual value with full provenance per …

    line 63
  7. Distinctive:

    If two tools disagree, name the structural reason rather than calling it a bug.

    line 64
  8. Distinctive:

    If the term is missing from the definitions file, say so, answer carefully from first principles, and flag that the file needs the term …

    line 65
  9. Distinctive:

    Never say a number is good or bad without its comparison basis.

    line 69
  10. Distinctive:

    Never compare a metric across tools without naming the definitional gap first.

    line 70
  11. Distinctive:

    Never quote a vendor authority score as an input to ranking.

    line 71

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Explain this number

Context load

Run rainmaker context --check first. It prints what exists, what is stale, and exits 1 if anything this skill requires is missing.

Then read, in this order:

  1. context/business.md in full. If absent, stop: "No business context. Run rainmaker audit, then the know-my-buyer skill."
  2. context/voice.md if this skill writes prose. If absent, stop and say so.
  3. context/glossary.md if this skill names products, features or competitors.
  4. data/strategy.json if this skill reads or writes strategy.
  5. Only the data/ files listed in this skill's Consumes table. Never crawl or call an API the core already covers.

If strategy.json.context_hash does not match the current hash of context/business.md, say exactly:

"Business context was edited after the strategy was written. Re-run know-my-buyer, or run rainmaker context --sync to accept the prose as authoritative."

Then stop.

If context/business.md carries confidence: stub, continue, and stamp every output with: "Built on a stub context. Nothing in it came from a buyer. Run know-my-buyer to replace it."

This skill is the one exception to the stop rules above. A user asking what a metric means is entitled to an answer whether or not a context exists. Skip straight to the procedure, and mention the missing context only if the question is about their own numbers rather than about the metric.

Consumes

FileWhyIf missing
skills/_shared/metric-definitions.mdthe canonical definitionsthis skill cannot run; the file is part of the package
data/snapshots/<latest>/*.jsononly when the user asks about their own numberanswer the general question and say the site data is absent

Produces

Nothing. This skill decides nothing and writes nothing. It exists so that no other skill has to carry a definition, and so that every number in every report traces back to one agreed meaning.

Procedure

  1. Identify which term is actually in play. Users often name a different metric from the one they are looking at: "traffic" might be sessions, users, clicks or impressions, and the answer differs for each.
  2. Read the entry in skills/_shared/metric-definitions.md. Give all three parts: what it is, how it is usually misread, and what to say instead. The second part is usually the one they needed.
  3. If the question is about the user's own number, read the relevant snapshot and quote the actual value with full provenance per skills/_shared/evidence-rules.md. Never invent an illustrative figure when a real one is available.
  4. If two tools disagree, name the structural reason rather than calling it a bug. Most disagreements are definitional: different identity models, different windows, different attribution, different sampling, or bot filtering applied at different points.
  5. If the term is missing from the definitions file, say so, answer carefully from first principles, and flag that the file needs the term added. Do not quietly invent an entry.

Decision rules

  • Never say a number is good or bad without its comparison basis. Good against what: the site's own prior window, the CTR curve at that position, or the threshold published by the tool.
  • Never compare a metric across tools without naming the definitional gap first.
  • Never quote a vendor authority score as an input to ranking. Say what it is: a third-party prediction.
  • Where a metric is an average of averages, say so before anything else. Average position is the common case and the most consequential.

Output

Short. Three parts, then the user's actual number if there is one.

Average position is the average rank of your URL for that query across every
impression in the window, blended across devices and countries.

Commonly misread as a rank. A page sitting at 3 in the UK and 30 in the US
reports around 16, a position it has never actually held.

Say instead: "average position 16, blended across markets", and filter by
market before drawing any conclusion.

Yours: /pricing averages 8.4 for "clm pricing" (gsc.json, 28d to 2026-08-09,
confidence 0.7). You sell into the UK and the US, and those two markets are
not separated in that number.

Done when

The user knows what the metric measures, the most likely way they were about to misread it, and the sentence to use instead. If their own number was involved, it carries file, field, window and confidence.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.