bookmap-addon-dev

A Claude skill that turns a natural-language trading idea into a complete, buildable Bookmap addon — a Java module written against the Bookmap Layer 1 (L1) API, packaged as a .jar, and loaded via Settings → Api plugins configuration.

This repo is the source of the skill, not an addon itself. When installed, it teaches Claude how to scaffold, build, and debug Bookmap addons, and gives it helper scripts to do the mechanical parts (environment checks, project scaffolding, Javadoc lookup, building the jar).

New here? Read SKILL.md — it is both the skill's runtime instructions and the best description of the end-to-end workflow. This README is for people working on the skill.

Installing from scratch? Start with SETUP.md — prerequisites and how to install the skill on each surface (Claude Code, claude.ai, Agent SDK).

---

What a "skill" is

A Claude skill is a folder that Claude loads on demand to gain a capability. It uses progressive disclosure:

1. Claude always sees the name + description from SKILL.md's frontmatter. The description is a big keyword net (mentions of "Bookmap addon", "indicator", velox.api.layer1, @Layer1SimpleAttachable, a trading idea, etc.) — that is what makes Claude decide to use it.
2. When triggered, Claude reads the body of SKILL.md — the guided workflow and step-by-step instructions.
3. Only when a step needs them does Claude open the reference docs (references/) or run the scripts (scripts/). This keeps the always-loaded context small.

So editing the skill is mostly editing Markdown and Python — there is no build step for the skill itself.

---

Repo layout

bookmap-addon-dev/
├── SKILL.md                  # ← the skill: frontmatter (trigger) + guided workflow (instructions)
├── SETUP.md                  # prerequisites + how to install the skill on each surface
├── README.md                 # this file (developer onboarding)
│
├── scripts/                  # Python 3, stdlib-only, cross-platform helpers Claude runs
│   ├── _bookmap_env.py       #   shared: locate a Bookmap install's JRE / ASM, Java-target logic
│   ├── check_prereqs.py      #   verify JDK/Gradle, locate Bookmap install + Javadoc jars
│   ├── new_project.py        #   scaffold a buildable Gradle project (Maven or offline mode)
│   ├── build_addon.py        #   compile → build/libs/<name>.jar (gradlew → gradle → javac fallback)
│   ├── javadoc_lookup.py     #   resolve exact class packages & method signatures from Javadoc
│   └── install_skill.py      #   install into ~/.claude/skills, or package a .skill zip
│
├── references/               # deep docs Claude opens only when a step needs them
│   ├── simplified-api.md     #   Simplified API (@Layer1SimpleAttachable / CustomModule)
│   ├── core-api.md           #   Core API (@Layer1Attachable / Layer1ApiFinishable)
│   ├── examples-catalog.md   #   74 official DemoStrategies mapped to what each shows
│   └── build-and-load.md     #   dependencies, build, loading, debugging, common failures
│
└── assets/                   # copied verbatim into scaffolded projects
    ├── project-template/     #   build.gradle, settings.gradle, starter addon, README
    └── gradle-wrapper/       #   pinned Gradle wrapper installed into new projects

The three moving parts work together: SKILL.md is the brain (when + how), scripts/ do the deterministic work, references/ hold the knowledge, and assets/ are the raw material the scripts stamp out into a user's project.

---

Prerequisites

These are for running/testing the skill (building an actual addon). Working on the skill's docs needs none of them.

Requirement	Needed for	Notes
Python 3.8+	The helper scripts	Standard library only — no pip install. On Windows use py/python.
JDK 17+ (with javac)	Compiling an addon	Only hard requirement to build. Jar targets Java 17 bytecode regardless of host JDK.
Bookmap (installed)	Loading, running, debugging; offline builds/Javadoc	Optional for building via Maven mode.
Internet (once)	Gradle wrapper / Maven fetch	Offline mode (--bookmap-lib) needs neither.

See SETUP.md for per-OS install commands. Quick check:

python3 scripts/check_prereqs.py        # Windows: py scripts\check_prereqs.py

---

Installing the skill

From the repo root (copies it into ~/.claude/skills/bookmap-addon-dev/):

python3 scripts/install_skill.py            # --force to overwrite; --dest ./.claude/skills for a repo

Then, in Claude Code, either describe what you want ("plot a custom moving average over the heatmap") or invoke /bookmap-addon-dev.

To package a .skill zip for claude.ai / the Skills API:

python3 scripts/install_skill.py package    # -> dist/bookmap-addon-dev.skill

Full surface-by-surface instructions (claude.ai, desktop, Agent SDK) are in SETUP.md. Note: skills don't sync across surfaces — install on each. On claude.ai the scripts run in Anthropic's sandbox and can't reach a local Bookmap install, so use Claude Code for local/offline builds.

---

How the end-user workflow flows

When triggered, Claude follows the guided workflow in SKILL.md. A typical build is:

check_prereqs.py   →   new_project.py   →   (write addon code)   →   build_addon.py   →   load in Bookmap
   (Step 1)              (Step 2)              (Step 3, +javadoc_lookup.py Step 4)  (Step 5)

Key design decisions baked into the skill (keep them in mind when editing):

• Simplified vs Core is exactly one flavor per project — never both. The whole workflow branches on this choice; don't blur it.
• Target Java 17 bytecode, not the install's bundled JRE. Bookmap finds the entry point by scanning bytecode with ASM, which reads a lower class-file version than the JRE can run. Newer bytecode → "No entry points found in jar". _bookmap_env.py detects the ASM ceiling only to warn.
• Prefer offline mode (--bookmap-lib) when the install dir is known: the API version always matches and no network is needed.
• Never guess API signatures — javadoc_lookup.py verifies against the real Javadoc for the user's version.

---

Working on the skill (how to update & improve it)

There's no compile/test framework — the skill is Markdown + stdlib Python. The loop is: edit → run the affected script locally → reinstall → try it in Claude.

Common changes

You want to…	Edit	Then verify with
Change when Claude uses the skill	description in SKILL.md frontmatter	Ask Claude something that should (and shouldn't) trigger it
Change how Claude works through a build	body of SKILL.md	Run through the workflow end to end
Fix/extend API knowledge	the relevant references/*.md	Cross-check against DemoStrategies + Javadoc (links below)
Add/adjust a script's behavior	scripts/*.py	Run the script directly (see below)
Change the generated project	assets/project-template/ (and gradle-wrapper/)	Scaffold a project and build it

Running the scripts directly while developing

# environment report
python3 scripts/check_prereqs.py

# scaffold into a throwaway dir (never overwrites the CWD; creates a new subdir)
python3 scripts/new_project.py --name "Test addon" --package com.acme.bookmap \
    --class TestAddon --flavor simplified --dir /tmp/test-addon

# build it (gradlew → system gradle → javac fallback)
python3 scripts/build_addon.py /tmp/test-addon \
    --bookmap-lib "/Applications/Bookmap.app/Contents/app/lib"   # macOS offline path

# resolve an API symbol
python3 scripts/javadoc_lookup.py --member registerIndicator --version 7.7.0.22

Scripts import a sibling _bookmap_env.py; running them as python3 scripts/<x>.py from the repo root puts that folder on sys.path, so imports resolve.

Constraints to preserve

• Stdlib only — no third-party Python deps. The scripts must run anywhere Python 3.8+ is present.
• Cross-platform — Windows / macOS / Linux. Use os.path, handle .exe/.bat, py vs python3.
• Non-destructive scaffolding — new_project.py must only ever create a new subdirectory, never write into or overwrite the CWD or its parents.
• Keep SKILL.md frontmatter and body in sync with the scripts — flags, defaults (e.g. API version 7.7.0.22, Java 17), and step numbers are referenced from both.
• .gitignore already excludes __pycache__/, *.pyc, dist/, *.skill — don't commit build artifacts.

After editing, reinstall to test in Claude

python3 scripts/install_skill.py --force

Skills are loaded from ~/.claude/skills/ (or a repo's .claude/skills/), so a code edit in this repo isn't picked up until you reinstall. For a team, install into the repo's .claude/skills/ and commit.

---

Keeping the API knowledge current

The default API version is 7.7.0.22 (latest at creation time). The API is versioned and back-compatible, but coordinates and signatures change between releases. When updating references, defer to live sources:

• DemoStrategies: https://github.com/BookmapAPI/DemoStrategies
• Knowledge base: https://bookmap.com/knowledgebase/docs/API
• Release notes: https://bookmap.com/knowledgebase/docs/KB-ReleaseNotes
• Javadoc (hosted): https://javadoc.bookmap.com/maven2/releases/com/bookmap/api/api-core/<version>/index.html (and .../api-simplified/<version>/...)

To bump the default API version, update DEFAULT_API_VERSION in new_project.py and javadoc_lookup.py, the examples in SKILL.md, and the dependency versions in references/build-and-load.md and assets/project-template/build.gradle.

---

Contributing

1. Make the change in the relevant SKILL.md / references/ / scripts/ / assets/ file.
2. Run the affected script(s) directly and, if it's a workflow change, walk the full path once.
3. python3 scripts/install_skill.py --force and try it in Claude Code with a realistic prompt.
4. Keep the constraints above (stdlib-only, cross-platform, non-destructive, docs↔scripts in sync).