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
• 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+ (xbbg 1.x requires this).
• 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

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.
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 materially diverges from 0.x (return shapes, default backend, available endpoints, kwarg aliases). Within the 1.x line, behavior also shifted between 1.0 → 1.1 → 1.2, most notably the Excel-shorthand alias table (Per, Currency, Days, Fill) was added in 1.2.0 and does not exist on 1.1.x.

The skill defaults to canonical Bloomberg element names (periodicitySelection="WEEKLY", currency="EUR", etc.) for cross-version safety, and includes a defensive-probe pattern that prints the actual return type and shape before building parsing logic on top of any xbbg call.

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. When uncertain whether a Bloomberg field or override exists, the skill consults the bundled schemas before guessing. xbbg.bschema(...) provides the same data at runtime on xbbg 1.x.
• 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.

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, 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.