Agent skill

Bench Hdr

by joaquinbejar in joaquinbejar/OrderBook-rs

Add or update an orderbook-rs hot-path latency benchmark that reports p50 / p99 / p99.9 / p99.99 via hdrhistogram, not the criterion default mean.

MITAuto-check: notes

Install Bench Hdr

skills CLI
$ npx skills add joaquinbejar/OrderBook-rs --skill bench-hdr -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install joaquinbejar/OrderBook-rs bench-hdr --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/joaquinbejar/OrderBook-rs.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/bench-hdr .claude/skills/bench-hdr && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
bench-hdr
GitHub stars
543
Token cost
~2.9k tokens
SKILL.md length
713 words
Files
1
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Add or update an orderbook-rs hot-path latency benchmark that reports p50 / p99 / p99.9 / p99.99 via hdrhistogram, not the criterion default mean.

  • Works in 10 steps: Scenario taxonomy → File placement → Register the bench in Cargo.toml → …
  • Adding a benchmark for an end-to-end scenario (add-only
  • SKILL.md covers When to invoke, Prerequisites and Procedure
  • Calls cargo and rg

What it does

Bench Hdr is an agent skill from joaquinbejar/OrderBook-rs. Add or update an orderbook-rs hot-path latency benchmark that reports p50 / p99 / p99.9 / p99.99 via hdrhistogram, not the criterion default mean. Use when adding a benchmark for an end-to-end scenario (add-only, cancel-only, aggressive walk, mixed 70/20/10, thin-book IOC sweep, mass-cancel burst, snapshot capture), or when updating an existing bench after a hot-path change. Handles warmup, coordinated-omission disclosure, and a short interpretation block for BENCH.md.

Its SKILL.md is about 2.9k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It works with Rust. The repository describes itself as: A high-performance, thread-safe limit order book implementation written in Rust. This project provides a comprehensive order matching engine designed for low-latency trading… The licence is MIT.

When your agent uses it

  • Adding a benchmark for an end-to-end scenario (add-only
  • Aggressive walk
  • Thin-book IOC sweep
  • Mass-cancel burst

Example prompts

  • “/bench-hdr”

Requirements

  • Pre-approved tools (allowed-tools): Read, Write, Edit, Grep, Glob, Bash

Workflow steps

10 steps, taken from the step headings in SKILL.md.

  1. Scenario taxonomy
  2. File placement
  3. Register the bench in Cargo.toml
  4. Template — measurement core (benches/order_book/hdr_common.rs)
  5. Template — the bench binary
  6. Coordinated-omission handling
  7. Run conditions — document in BENCH.md
  8. BENCH.md template block
  9. After writing
  10. Relationship to existing Criterion benches

What it can do on your machine

Read from SKILL.md and the folder at commit 54df8eb. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Write
    • Edit
    • Grep
    • Glob
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • cargo
    • rg

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Bench Hdr loads about 2.9k tokens when it runs. Until then it costs about 121 tokens; SKILL.md has 713 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~121
When it runs · the whole SKILL.md, loaded when a task matches
~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from joaquinbejar/OrderBook-rs at commit 54df8eb, republished under its MIT licence (© joaquinbejar). 713 words, ~2,854 tokens.

Download SKILL.mdSave it as .claude/skills/bench-hdr/SKILL.md (or your agent's skills folder).
name
bench-hdr
description
Add or update an orderbook-rs hot-path latency benchmark that reports p50 / p99 / p99.9 / p99.99 via hdrhistogram, not the criterion default mean. Use when adding a benchmark for an end-to-end scenario (add-only, cancel-only, aggressive walk, mixed 70/20/10, thin-book IOC sweep, mass-cancel burst, snapshot capture), or when updating an existing bench after a hot-path change. Handles warmup, coordinated-omission disclosure, and a short interpretation block for BENCH.md.
allowed-tools
Read, Write, Edit, Grep, Glob, Bash

Skill: bench-hdr

Generates or updates a reproducible local benchmark for the orderbook-rs hot path. Output is an HDR-histogram dump with tail quantiles and a short interpretive paragraph that goes into BENCH.md.

Criterion ships with html_reports in this crate, but its default output is mean-centric and drops the tails. The hot-path SLO for a matching engine is p99 / p99.9 / p99.99; mean is a vanity metric. This skill adds a parallel hdrhistogram pipeline that lives alongside the Criterion benches.

When to invoke

  • Adding a benchmark for a new scenario.
  • Re-running benchmarks after a change to matching / operations / modifications / repricing / mass_cancel / fees to document p99 movement.
  • User says "benchmark this", "add a bench", "measure p99.9", "update BENCH.md".

Prerequisites

The crate already depends on criterion = { version = "0.8", features = ["html_reports"] } in Cargo.toml and has a benches/ directory organized under benches/order_book/. Before the first bench-hdr bench, add hdrhistogram as a dev-dependency:

cargo add --dev hdrhistogram@^7

Confirm the addition with rg -n 'hdrhistogram' Cargo.toml.

Procedure

1. Scenario taxonomy

Pick exactly one per bench file. Each lives under benches/order_book/ alongside the existing Criterion benches.

ScenarioInput profile
add_onlyPure passive limit submissions, no crossings. Measures insert cost.
cancel_onlyPre-loaded book, cancel workload. Measures DashMap lookup + unlink.
aggressive_walkTaker IOC sweeps across several levels. Measures fill-loop tail.
mixed_70_20_1070% submits, 20% cancels, 10% aggressive IOC. Most "realistic".
thin_book_sweepBook near-empty, IOC probing. Exercises partial-fill / reject path.
mass_cancel_burstDense book, then one mass-cancel. Measures bulk-cancel worst case.
snapshot_captureDense book, repeated snapshot() / snapshot_package() calls.
2. File placement
  • Bench file: benches/order_book/<scenario>_hdr.rs (the _hdr suffix keeps it visually distinct from the existing Criterion benches; they coexist).
  • Workload helpers: benches/order_book/hdr_common.rs.
  • HDR recorder wrapper: a small record helper inline in hdr_common.rs.
  • Output directory for raw histograms: target/bench-hdr/<scenario>.hgrm (already inside target/, so already gitignored).
  • Summary table: BENCH.md at the repo root (committed).
3. Register the bench in Cargo.toml
toml
[[bench]]
name = "mixed_70_20_10_hdr"
path = "benches/order_book/mixed_70_20_10_hdr.rs"
harness = false

harness = false so the bench is a plain binary and we control the measurement loop. The default Criterion harness is not suitable for tail latency — we need per-sample recording into an HDR histogram, not a wall-clock-bound iteration count driven by statistical convergence.

4. Template — measurement core (benches/order_book/hdr_common.rs)
rust
use hdrhistogram::Histogram;
use std::time::Instant;

/// Histogram sized for 1 ns .. 1 s with 3 significant figures.
pub fn new_histogram() -> Histogram<u64> {
    Histogram::<u64>::new_with_bounds(1, 1_000_000_000, 3).expect("hist bounds")
}

/// Measure a closure once, record nanoseconds into the histogram.
#[inline(always)]
pub fn record<F, R>(h: &mut Histogram<u64>, f: F) -> R
where
    F: FnOnce() -> R,
{
    let t0 = Instant::now();
    let r = std::hint::black_box(f());
    let elapsed = t0.elapsed().as_nanos() as u64;
    h.record(elapsed.max(1)).expect("record");
    r
}

pub fn report(name: &str, h: &Histogram<u64>) {
    println!("scenario   : {}", name);
    println!("samples    : {}", h.len());
    println!("p50   (ns) : {}", h.value_at_quantile(0.50));
    println!("p99   (ns) : {}", h.value_at_quantile(0.99));
    println!("p99.9 (ns) : {}", h.value_at_quantile(0.999));
    println!("p99.99(ns) : {}", h.value_at_quantile(0.9999));
    println!("max   (ns) : {}", h.max());
    println!("min   (ns) : {}", h.min());
}

pub fn persist(name: &str, h: &Histogram<u64>) -> std::io::Result<()> {
    use hdrhistogram::serialization::V2Serializer;
    std::fs::create_dir_all("target/bench-hdr")?;
    let path = format!("target/bench-hdr/{}.hgrm", name);
    let mut f = std::fs::File::create(&path)?;
    V2Serializer::new()
        .serialize(h, &mut f)
        .map_err(|e| std::io::Error::new(std::io::ErrorKind::Other, e))?;
    eprintln!("wrote {}", path);
    Ok(())
}
5. Template — the bench binary

Example benches/order_book/mixed_70_20_10_hdr.rs (adapt the exact call signatures to the public API as it exists at the time the bench is written; verify with rg -n 'pub fn submit|pub fn cancel|pub fn mass_cancel' src/orderbook/operations.rs src/orderbook/modifications.rs src/orderbook/mass_cancel.rs):

rust
#[path = "hdr_common.rs"]
mod hdr_common;

use hdr_common::{new_histogram, persist, record, report};
use orderbook_rs::prelude::*;

const WARMUP_OPS:   usize =   200_000;
const MEASURED_OPS: usize = 1_000_000;
const SEED:         u64   = 0xA5A5_A5A5;

enum Op {
    Submit { id: Id, owner: u64, side: Side, price: Price, qty: Quantity, tif: TimeInForce },
    Cancel(Id),
    Aggressive { id: Id, owner: u64, side: Side, qty: Quantity },
}

fn build_mixed_workload(n: usize, seed: u64) -> Vec<Op> {
    // Deterministic PRNG from `seed`; no rand crate — use a small xorshift so the bench
    // is self-contained and reproducible. Tight price band (99..=101) for frequent
    // crossings on the aggressive slice.
    let mut s = seed;
    let mut next = || { s ^= s << 13; s ^= s >> 7; s ^= s << 17; s };
    let mut ops = Vec::with_capacity(n);
    for i in 0..n {
        let bucket = next() % 100;
        let id = Id::from_u64(i as u64 + 1);
        let owner = (next() % 4) + 1;
        let side = if next() % 2 == 0 { Side::Buy } else { Side::Sell };
        let price = Price::from_u64(99 + (next() % 3));
        let qty = Quantity::from_u64(1 + (next() % 100));
        if bucket < 70 {
            ops.push(Op::Submit { id, owner, side, price, qty, tif: TimeInForce::Gtc });
        } else if bucket < 90 {
            ops.push(Op::Cancel(Id::from_u64(1 + (next() % (i as u64).max(1)))));
        } else {
            ops.push(Op::Aggressive { id, owner, side, qty });
        }
    }
    ops
}

fn apply(book: &OrderBook<()>, op: &Op) {
    match op {
        Op::Submit { id, owner, side, price, qty, tif } => {
            let _ = book.submit_limit(*id, *owner, *side, *price, *qty, *tif);
        }
        Op::Cancel(id) => {
            let _ = book.cancel(*id);
        }
        Op::Aggressive { id, owner, side, qty } => {
            let _ = book.submit_market(*id, *owner, *side, *qty);
        }
    }
}

fn main() {
    let workload = build_mixed_workload(WARMUP_OPS + MEASURED_OPS, SEED);
    let book = OrderBook::<()>::new("BENCH");
    let mut h = new_histogram();

    // Warmup — discarded.
    for op in &workload[..WARMUP_OPS] { apply(&book, op); }

    // Measurement.
    for op in &workload[WARMUP_OPS..] {
        record(&mut h, || apply(&book, op));
    }

    report("mixed_70_20_10", &h);
    persist("mixed_70_20_10", &h).expect("persist");
}
Show full SKILL.md (327 more words)Show less
6. Coordinated-omission handling

The loop above is a closed-loop benchmark (the driver waits for each op to finish before issuing the next). Under saturation this systematically under-reports tail latency because coordinated omission hides queueing stalls. Two options; pick one and document the choice in BENCH.md:

  • Option A — open-loop with expected arrival interval. Record now - scheduled_arrival, not now - ingest_start. Requires picking a target rate (e.g. 500k ops/s). CO is handled by construction, no separate disclosure.
  • Option B — closed-loop with explicit "pure service time" caveat. Call out in BENCH.md that the numbers are pure service time, not tail under load. Useful as a lower bound and a regression signal, but not a production SLO.

For a regression-signal bench inside a lock-free crate, Option B is acceptable if you are explicit. Option A, done sloppily, is worse than Option B done honestly.

7. Run conditions — document in BENCH.md

Missing entries are a negative signal to any reviewer.

  • CPU model, core count, frequency governor (performance or powersave).
  • Whether the bench was CPU-pinned (taskset -c 2 cargo bench --bench mixed_70_20_10_hdr) and, if so, which core and whether it was isolated.
  • Hyperthreads, nohz_full, rcu_nocbs, SMT state.
  • Warmup ops, measured ops, workload seed (fixed per the template).
  • Rust version, --release, LTO setting, RUSTFLAGS.
  • Allocator — system allocator unless the crate has been configured otherwise.
8. BENCH.md template block
markdown
## mixed_70_20_10

Workload: 70% submits, 20% cancels, 10% aggressive market (IOC-like). Seed 0xA5A5A5A5.
Samples: 1,000,000 after 200,000 warmup ops.
Loop: closed-loop. Reported numbers are pure service time; see Methodology §CO.

| Quantile  | Latency     |
|-----------|-------------|
| p50       | XXX ns      |
| p99       | XXX ns      |
| p99.9     | XXX ns      |
| p99.99    | XXX ns      |

**Where the tail comes from.**
[One honest paragraph. Acceptable content: cache miss on `SkipMap` price lookup beyond L2,
branch mispredict on the fill loop when the book is thin, allocator jitter from
`BookChangeEvent` emission when the outbound `Vec` resizes, `DashMap` shard contention on
the order-id index under concurrent writers. Do not write "probably jitter" — if you
don't know, say "the dominant contributor is not yet identified; next step is
`perf stat -e <events>` on the measured window."]
9. After writing
  • cargo bench --bench <scenario>_hdr.
  • Fill the BENCH.md table with the output.
  • target/bench-hdr/*.hgrm is already under target/ so it is gitignored; do not commit the histograms. Commit BENCH.md.
  • Commit with a conventional prefix: bench: add <scenario> HDR histogram bench.
10. Relationship to existing Criterion benches

The Criterion benches under benches/order_book/ (add_orders.rs, match_orders.rs, mass_cancel.rs, matching.rs, mixed_operations.rs, replay.rs, snapshot.rs, update_orders.rs) stay as they are — they provide the mean-centric statistical comparison that Criterion does well and publish HTML reports to target/criterion/.

The _hdr benches coexist with them and are the source of truth for tail-latency claims in BENCH.md and any release notes that quote p99 / p99.9 / p99.99 numbers.

© joaquinbejar, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/bench-hdr of joaquinbejar/OrderBook-rs.

Open the folder on GitHubat commit 54df8eb

Compare with similar skills

Bench Hdr next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Bench Hdr compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Bench Hdr this skilljoaquinbejar/OrderBook-rs543—~2.9kAutomated safety check: NotesMIT
Update V8 Versionopeninterpreter/openinterpreter69k2 repos~845Automated safety check: PassApache-2.0
Firecrawl Page Scrape Integrationfirecrawl/firecrawl190k1 repos~944Automated safety check: PassISC
Migrate Core Code to Submodulestinyhumansai/openhuman42k—~2.6kAutomated safety check: PassGPL-3.0
Rust TDD Workflowrtk-ai/rtk83k—~753Automated safety check: NotesApache-2.0
OpenLogi macOS Permissions TriageAprilNEA/OpenLogi23k—~2.5kAutomated safety check: NotesApache-2.0

Similar skills

  • Update V8 Version

    openinterpreter/openinterpreter

    Bumps the pinned v8 and rusty_v8 versions in Codex, validates the release-candidate path with the v8-canary check, and traces failures to upstream build changes.

    69k GitHub starsUsed in 2 repos~845 tokens
    DevOps & CloudAuto-check passed
  • Adds Firecrawl's /scrape endpoint to application code to pull markdown, HTML, links, screenshots or structured data from a single known URL.

    190k GitHub starsUsed in 1 repo~944 tokens
    Data & AnalyticsAuto-check passed
  • Migrate Core Code to Submodules

    tinyhumansai/openhuman

    Plans and carries out moving non-host-specific code and its tests from the OpenHuman core into vendored tiny submodule libraries, then releases the submodule and re-pins the host.

    42k GitHub stars~2.6k tokensUpdated today
    DevelopmentAuto-check passed
  • Enforces red-green-refactor for Rust work, with idiomatic test patterns, a naming convention and a pre-commit gate of cargo fmt, clippy and test.

    83k GitHub stars~753 tokensUpdated today
    Testing & QAAuto-check: notes
  • Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated today
    DevelopmentAuto-check: notes
  • Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook.

    5.6k GitHub starsUsed in 3 repos~1.1k tokens
    DevelopmentAuto-check passed

More from joaquinbejar/OrderBook-rs

  • Proptest Invariant

    joaquinbejar/OrderBook-rs

    Generate a proptest block for a named orderbook-rs matching-engine invariant.

    543 GitHub stars~2.8k tokensUpdated 3 days ago
    Auto-check: notes
  • Source Command Implement Roadmap

    joaquinbejar/OrderBook-rs

    Autonomously implement every roadmap issue end-to-end (PR → Copilot review → respond → green CI → merge → roadmap update) until done

    543 GitHub stars~4.2k tokensUpdated 3 days ago
    Auto-check passed

Works with

Questions about Bench Hdr

What does Bench Hdr do?

Add or update an orderbook-rs hot-path latency benchmark that reports p50 / p99 / p99.9 / p99.99 via hdrhistogram, not the criterion default mean. Bench Hdr is an agent skill from joaquinbejar/OrderBook-rs.99 via hdrhistogram, not the criterion default mean.

When should I use Bench Hdr?

Bench Hdr fits situations like: adding a benchmark for an end-to-end scenario (add-only; aggressive walk; thin-book IOC sweep; mass-cancel burst.

How do I install Bench Hdr in Claude Code?

Run `npx skills add joaquinbejar/OrderBook-rs --skill bench-hdr -a claude-code`. Or copy the skill folder (.agents/skills/bench-hdr in joaquinbejar/OrderBook-rs) into .claude/skills/bench-hdr in your project. Claude Code loads it when a task matches its description.

How do I install Bench Hdr in Codex?

Run `npx skills add joaquinbejar/OrderBook-rs --skill bench-hdr -a codex`. Or copy the skill folder (.agents/skills/bench-hdr in joaquinbejar/OrderBook-rs) into .agents/skills/bench-hdr in your project. Codex loads it when a task matches its description.

Can I use Bench Hdr in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add joaquinbejar/OrderBook-rs --skill bench-hdr -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bench-hdr, .gemini/skills/bench-hdr, .github/skills/bench-hdr and .opencode/skills/bench-hdr in your project.

What does Bench Hdr need to run?

Going by SKILL.md and its folder, Bench Hdr needs the command-line tools its instructions call (cargo and rg). Its frontmatter pre-approves these tools: Read, Write, Edit, Grep, Glob, Bash.

Does Bench Hdr access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Bench Hdr safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Bench Hdr use?

Bench Hdr is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Bench Hdr use?

About 2.9k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Bench Hdr?

Skills that share tags, products or a category with Bench Hdr: Update V8 Version (openinterpreter/openinterpreter, 69k stars), Firecrawl Page Scrape Integration (firecrawl/firecrawl, 190k stars), Migrate Core Code to Submodules (tinyhumansai/openhuman, 42k stars) and Rust TDD Workflow (rtk-ai/rtk, 83k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Bench Hdr?

joaquinbejar (a GitHub user) maintains it in joaquinbejar/OrderBook-rs, which has 543 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 5, 2026.

Source: joaquinbejar/OrderBook-rs on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.