blpapi-expert

A Claude Skill that makes Claude reliably good at writing Bloomberg API (blpapi / xbbg) code.

Without this skill, Claude tends to fabricate plausible-looking but wrong field names, override names, request shapes, and Element-tree parsing patterns. With it loaded, Claude defaults to the canonical patterns, consults bundled Bloomberg schema dumps before guessing, and cites references for non-obvious choices.

What it covers

• Reference data (bdp): point-in-time fields, fundamentals, identifier crosswalks
• Bulk fields (bds): index members, option chains, holders
• Historical data (bdh): time series with adjustment, currency, calendar, and fiscal-period overrides
• Intraday bars (bdib) and ticks (bdtick)
• Real-time subscriptions (subscribe / asubscribe): xbbg 1.x native subscription support
• Derivatives: listed-option chains, IVOL_* fields, vol surface construction (with the percent-vs-decimal IV gotcha pinned)
• Overrides: top-level vs field overrides vs table overrides; FUND_PER, EQY_FUND_CRNCY, VWAP_*, etc.
• Yellow keys / ticker formats: including FX forward-points conventions and hedged-index ticker families
• Errors: responseError / securityError / fieldExceptions taxonomy and partial-response handling
• Setup and preflight tooling: assets/setup.py (one-command install plus validation) and assets/preflight.py (a live probe that re-derives response shapes, dtypes, SEMI_LONG and Excel-alias behavior on the installed xbbg, so the skill trusts the runtime over its own prose)
• Schemas -- bundled machine-generated dumps of every //blp/<service> schema: request types, elements, datatypes, enum values, and the real-time mktdata field list. (Reference-data field and override names are confirmed at runtime via //blp/apiflds, not from these static dumps, which describe request shape rather than the field dictionary.)

Scope is Bloomberg Desktop API (Terminal-attached local sessions). B-PIPE / Server API / Platform / EMSX / Excel COM are explicitly out-of-scope; the skill says so and asks before extrapolating.

Install

The skill is shipped as a single blpapi-expert.skill file (a zip bundle) at the repository root.

In Claude.ai (recommended for most users)

1. Download blpapi-expert.skill.
2. Open a Claude.ai chat, drag the file into the conversation.
3. Confirm install when prompted.
4. Restart any open Claude sessions for them to pick up the install. New sessions started after install pick it up automatically.

In Claude Code

Drop the blpapi-expert/ folder into your Claude Code skills directory: ~/.claude/skills/ on macOS/Linux, or %USERPROFILE%\.claude\skills\ (i.e. C:\Users\<you>\.claude\skills\) on Windows. The skill loads on next session start.

(Note: %USERPROFILE%\.claude, not %APPDATA%\Claude -- the latter is Claude Desktop's directory, where Claude Code does not look.)

Prerequisites

To actually run code generated under this skill, you need:

• A Bloomberg Terminal running and logged in on the same machine.
• Python 3.10 through 3.14 (xbbg 1.x declares >=3.10,<3.15).
• blpapi (Bloomberg's Python SDK, not on PyPI):

  pip install --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/ blpapi

• xbbg (recommended wrapper for analytical work):

  pip install xbbg

Or let the bundled tooling do it: python assets/setup.py (inside the skill folder) installs anything missing and validates the whole path against the live Terminal; --check validates without installing; pwsh assets/setup.ps1 is the Windows wrapper.

The skill itself works fine without a Terminal (Claude can write Bloomberg code anywhere), but verifying generated code requires the Terminal.

What's in the bundle

The blpapi-expert/ folder (and the .skill zip of it) contains:

Path	Purpose
SKILL.md	Top-level skill description, decision tree, canonical patterns, gotchas
references/*.md	Eight topic references, load on demand. developer_guide.md is the full Bloomberg Core Developer Guide as a deep fallback.
assets/schemas/*.txt	Authoritative schema dumps of //blp/refdata, //blp/mktdata, //blp/apiflds, //blp/instruments. Generated by dump_schemas.py.
assets/examples/	Bloomberg-authored canonical Python examples, untouched.
assets/preflight.py	Live probe: versions, xbbg method surface, Format members, and the real bdp / bdh / bds shapes and dtypes on the installed version. Never hangs; degrades gracefully without a Terminal.
assets/setup.py, assets/setup.ps1, assets/requirements.txt	One-command install (blpapi from Bloomberg's index, xbbg from PyPI) followed by the preflight probe. --check validates only.
tests.md	Should-trigger / should-not-trigger / expected-behavior prompts used during development. Not auto-loaded.

Schema regeneration

The bundled schema dumps reflect a specific Bloomberg API version and the bundled Bloomberg user's entitlements. To regenerate against your own Terminal:

cd blpapi-expert/assets/schemas/
python dump_schemas.py

This drops schema_refdata.txt, schema_mktdata.txt, schema_apiflds.txt, schema_instruments.txt next to the script. Run it whenever the skill flags an unexpected field/override or when your entitlements change.

xbbg version awareness

xbbg 1.x is a Rust-backed rewrite that materially diverges from 0.x (return shapes, default backend, available endpoints, kwarg aliases), and the 1.x line releases often: 1.2 through 1.4.6 shipped between spring and August 2026. Within 1.x, the Excel-shorthand alias table (Per, Currency, Days, Fill) arrived in 1.2.0 and is absent on 1.1.x and older, where those kwargs are rejected.

The skill therefore defaults to canonical Bloomberg element names (periodicitySelection="WEEKLY", currency="EUR", etc.), which work on every 1.x release, prints xbbg.__version__ as a preflight step, and includes a defensive-probe pattern that prints the actual return type and shape before building parsing logic on top of any xbbg call. The references were verified live against a Bloomberg Terminal on both xbbg 1.1.0 (blpapi 3.26.3.1) and xbbg 1.4.6 (blpapi 3.26.7.1, pandas 3.0, in a clean venv) on 2026-08-16; when the installed version is newer still, the runtime wins over the prose. What changed between those two: Format.SEMI_LONG pivots on 1.4.6 (a no-op on 1.1.x), the Excel-alias table is present on 1.4.6, and bdib gained a trailing value column. What held: the mix-dependent bdp dtype, bdh shape and typing, LONG_TYPED / LONG_WITH_METADATA columns, verbatim bds subfield columns, UTC-tagged intraday timestamps, bschema / bflds / fieldInfo.

Last checked against PyPI on 2026-08-16: xbbg 1.4.6 (released 2026-08-07), Python >=3.10,<3.15, Apache-2.0, source at github.com/xbbg-org/xbbg, docs at xbbg.org.

Repository structure

.
├── README.md                       # this file
├── LICENSE                         # MIT
├── pack.ps1                        # PowerShell, repackage the .skill bundle
├── blpapi-expert/                  # the skill source, folder version
└── blpapi-expert.skill             # built bundle, drop into Claude.ai

blpapi-expert/ and blpapi-expert.skill are the user-facing deliverables.

How this was built

The skill was developed iteratively against a real Bloomberg Terminal.

Key design decisions (locked):

• xbbg as the default wrapper for analytical work; raw blpapi only for legacy compatibility, custom session options, or precise event-loop control.
• Desktop API only in scope. B-PIPE / Server / Platform / EMSX are explicitly out-of-scope.
• Schema dumps as ground truth for request shape. When uncertain whether a request element, enum, or datatype exists, the skill consults the bundled schemas before guessing (xbbg.bschema(...) provides the same data at runtime). Reference-data field and override names are confirmed at runtime via //blp/apiflds, since the static dumps don't enumerate the field dictionary.
• Pushy SKILL.md description to combat under-triggering. The skill loads on Bloomberg-style ticker syntax (AAPL US Equity, SPX Index, EURUSD Curncy) even when the user doesn't say "Bloomberg" or "blpapi" explicitly.

Repackaging

If you fork or modify the skill source under blpapi-expert/, rebuild the .skill bundle with:

.\pack.ps1

The script copies blpapi-expert/ to a temp staging folder, excludes any *.zip artifacts, and produces a fresh blpapi-expert.skill at the repository root. See pack.ps1 for details.

Changelog

• 1.1.2 (2026-08-16): verified live on xbbg 1.4.6 (clean venv, blpapi 3.26.7.1, pandas 3.0) alongside the desk's 1.1.0, both against a logged-in Terminal, using assets/preflight.py plus an extra probe. Sharpened the version-sensitive claims accordingly: Format.SEMI_LONG pivots on 1.4.6 ([ticker, date, <fields>]) and was a no-op only on 1.1.x; the mixed-type bdp column is a string dtype (object on pandas 2, str on pandas 3); bdib on 1.4.6 appends a value column. Everything else in the references held unchanged on 1.4.6.
• 1.1.1 (2026-08-16): three refinements found while reconciling a Terminal-verified local fork: historical.md no longer suggests Format.SEMI_LONG for the wide layout (it does not pivot on xbbg 1.1.x; pivot explicitly), the rejected-alias error text in historical.md and overrides.md now carries the exact BlpValidationError: Invalid argument: element '<X>' not found string, and reference_data.md explains when coercion is needed.
• 1.1.0 (2026-08-16): currency refresh plus tooling. Re-verified the xbbg 1.x premise against PyPI (latest 1.4.6, Python 3.10 to 3.14, Apache-2.0, source now under xbbg-org). Reframed the version guidance so the Excel-alias caveat reads as a legacy (1.1.x and older) note rather than the frontier; named the polars / pyarrow / duckdb backends. Ported assets/preflight.py, assets/setup.py, assets/setup.ps1, and assets/requirements.txt from a Terminal-verified local fork, together with its corrections: bdp's value dtype under Format.LONG is mix-dependent rather than always string, Format.SEMI_LONG does not pivot on xbbg 1.1.x, Format.LONG_WITH_METADATA exists, and the exact UserWarning / BlpValidationError text for rejected Excel aliases (all re-confirmed live on 2026-08-16 against xbbg 1.1.0). Removed a stale "schemas not generated yet" contingency, tightened the gotchas list, added metadata.version to the frontmatter, and made pack.ps1 exit 0 on success.
• 1.0.0 (2026-06-28): first reviewed public release (tag v1.0.0), incorporating the deployment-readiness review fixes over the 2026-05-01 initial commit.

License

MIT (see LICENSE) covers this project's original material: SKILL.md, the topic references (except developer_guide.md), the schema-dump tooling, the packaging script, and this README. Bundled third-party content keeps its own terms, noted below.

The Bloomberg Core Developer Guide PDF (text-converted into blpapi-expert/references/developer_guide.md) is © Bloomberg Finance L.P. and its licensors. It's included verbatim because anyone using this skill needs a Bloomberg Terminal (and therefore a Bloomberg license) to actually run the generated code. If you're redistributing without that assumption, strip the developer guide first.

The bundled Bloomberg-authored Python examples in blpapi-expert/assets/examples/ are © Bloomberg Finance L.P. and distributed under the terms Bloomberg attaches to its SDK examples (generally permissive for users with a valid Bloomberg license).

Acknowledgments

• xbbg (docs at xbbg.org), Apache 2.0, the reason most analytical Bloomberg work in Python is one-liners instead of Element-tree gymnastics.
• Anthropic Claude Skills the framework this is built on.
• Bloomberg L.P., for the Terminal and the SDK that make all of this possible.