Using BMO with AI assistants

BMO ships an agent skill: a folder of instructions, API references and runnable example scripts that teaches AI coding assistants such as Claude Code how to write BMO simulations. It covers units and coordinate conventions, the choice of beam model, all component constructors, detector readout, rendering and common pitfalls.

Installation

The skill is part of the package, in the skills/beamletoptics folder of the installed package directory. Copy the version that matches your installed BMO into your project with

using BeamletOptics
BeamletOptics.install_agent_skill()   # -> ./.claude/skills/beamletoptics

For a personal installation that applies to all projects, pass the user-level skill directory:

BeamletOptics.install_agent_skill(joinpath(homedir(), ".claude", "skills"))

Run the command again after Pkg.update to keep the skill in sync with the package version.

BeamletOptics.install_agent_skill Function

install_agent_skill(dest = joinpath(pwd(), ".claude", "skills"))

Copies the agent skill that ships with the installed BeamletOptics version into joinpath(dest, "beamletoptics") and returns that path. The skill teaches AI coding assistants (e.g. Claude Code) how to write BeamletOptics simulations.

The default dest is the project-level skill directory of Claude Code in the current working directory. Use e.g. joinpath(homedir(), ".claude", "skills") for a personal installation.

An existing beamletoptics skill in dest is replaced, so calling this function again after Pkg.update keeps the skill in sync with the installed package version. Local edits to the copy are lost.

File permissions

Pkg installs packages read-only. The copied files are made writable so that the copy can be edited and replaced later.

source

Installing from GitHub

The skill can also be installed with npx skills add JuliaPhysics/BeamletOptics.jl. This copy follows the development branch and can be newer than your installed BMO release. The skill records the BMO version it describes (beamletoptics-version in SKILL.md) and instructs the assistant to verify signatures when the versions differ.

Developing BMO with an assistant

The skill describes how to use BMO. Instructions for changing the package itself (design philosophy, code conventions, tests) are in AGENTS.md at the root of the repository. CLAUDE.md and GEMINI.md point to it.