Marc
cf31829509
The stale 119 was the least of it. A parallel audit of the repo against the live API found
defects that would make an agent following this playbook produce wrong answers or 403s.
Counts and the glossary:
- 120 metrics, not 119; 122 physical, not 121; quality is 11 physical / 9 sold, not 10/8.
- `baseAsset` was MISSING from a glossary that claims to list every metric — undocumented
from the day migration 007 added it. Wording taken from the live catalog entry.
- Reconciled in both directions: 0 documented keys that do not exist, 0 live keys missing.
- The "(declared `ratio`)" note on the two DepthReachPct rows is gone — that unit fix shipped.
Playbook errors, each verified against api/src:
- `/v1/latest` buckets at the CALLER'S PLAN granularity, not 5m (free 1d, pro 1h). A free
key's "latest" can be a day old and nothing in the response says so. The file said 5m.
- `5m` is max/ultra only and asking finer than the plan floor 403s, so the default advice
("hours to a few days -> 5m") failed for every free and pro key. Also removed a reference
to `1m` granularity: no such interval exists, the set is 5m/1h/1d.
- FIVE columns 400 the whole request if named in `columns=` (bookSynced, missingTrades,
quoteAsset, baseAsset, enrichmentTs) — the file warned about one and framed the two
harmless internal ones as the danger. Nothing in the catalog marks them.
- There is NO spread metric. The catalog has bestBid/bestAsk and a spread must be derived.
A worked example asked to chart one, and "spread" was mapped to depth keys, which are
resting size, not the distance between the sides.
- History depth is clamped silently and unheadered. Added the rule, because the natural
narration of a short series is "only N days of data" — retention framing, and retention
is infinite.
Also: bybit's maintainedDepth is 1,000 not 200 (the callout contradicted its own 12.5x,
which comes from okx's 400); the Units list was missing `percent` and `seconds`; cmc
liquidity/volume are per-pair, not market-wide; `BLACKFORGE_BASE_URL` is the ORIGIN and
setting it to the documented `/v1` base makes every request 404; only the column gate
degrades silently while venues and intervals 403; and the dashboard nav has no "Keys" —
API keys are on the API screen.
Adds scripts/check-catalog-sync.mjs: glossary completeness both ways, per-row unit and min
plan, per-family counts, and every prose count, against the PUBLIC catalog — no key, no
sibling checkout, and non-zero exit when the catalog cannot be read rather than a false
pass. All five failure modes proven by breaking them on purpose. It documents what it
cannot check: queryability is not exposed on the catalog at all.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.1 KiB
blackforge — agent skill
An agent skill that teaches any skills-compatible coding
agent (Claude Code, Cursor, and others) to answer crypto market-data questions by orchestrating
the BlackForge MCP tools (preferred) or the blackforge CLI. It is a thin
orchestration + interpretation layer — it never reimplements the API.
BlackForge stores one wide row per (exchange, symbol) per closed 5-minute window — 120
measurement columns (order-book depth and depth walls, order-ladder rungs, resting-liquidity
add/withdraw, price-level lifetime, trade timing, outsized-trade counts, market-cap and attention
enrichment, and a per-row quality bitmask) across 9 spot exchanges and ~11,800 spot pairs. The skill knows
that vocabulary and the discover → pick → call → interpret playbook, and it frames every returned
column as a measurement with a definition, never as a trade call.
Install
Install with the skills CLI — GitHub is the registry:
npx skills add blackforge-so/skill # into this project's skills dir
npx skills add blackforge-so/skill -g # or globally (user-level)
skills installs into whichever skills directory your agent uses (.claude/skills/ or
.agents/skills/) and detects the agent automatically. Then configure access — either the
BlackForge MCP server (preferred) or the blackforge CLI — and get an API key at
app.blackforge.so → API. See references/setup.md.
Contents
| Path | What |
|---|---|
SKILL.md |
The skill: frontmatter trigger description + the playbook |
references/metrics-glossary.md |
All 120 metrics grouped by family, each with its measurement definition and min plan |
references/setup.md |
How to install the skill, configure the MCP server or CLI, and get an API key |
scripts/latest-json.sh |
Optional CLI wrapper: dump the latest bucket for a pair as JSON |
scripts/check-catalog-sync.mjs |
Fails if these docs disagree with the live catalog — run it before publishing |
evals/trigger-eval.json |
Trigger eval set (should / should-not queries) for description tuning |
Source of truth
This GitHub repo is the versioned source. npx skills add blackforge-so/skill installs a copy into
your agent's skills directory — regenerate it from here rather than editing the installed copy.
Run this before you publish a change:
node scripts/check-catalog-sync.mjs
It reads the public catalog — no key, no sibling checkout — and fails if the glossary has gained or lost a metric, if any documented unit or min plan disagrees with the live one, if a family's count is wrong, or if any prose here states a column count that is not real. It exits non-zero when the catalog cannot be reached, rather than reporting success against a source it never read.
This exists because the count has drifted three separate times across the product, and because a
glossary that has silently lost one row looks exactly like a complete one. baseAsset went
undocumented here from the day migration 007 added it until 2026-07-28.