Ship the agent skills inside the package and add an agent_skills entry point

.claude-plugin/plugin.json

@@ -9,5 +9,6 @@
   "homepage": "https://gpcam.readthedocs.io",
   "repository": "https://github.com/lbl-camera/gpCAM",
   "license": "GPL-3.0",
-  "keywords": ["gaussian-process", "bayesian-optimization", "autonomous-experiments", "gpcam"]
+  "keywords": ["gaussian-process", "bayesian-optimization", "autonomous-experiments", "gpcam"],
+  "skills": "./gpcam/skills/"
 }

CLAUDE.md

@@ -12,28 +12,28 @@ This file serves two audiences:
 
 You are helping scientists design autonomous experiments using gpCAM, a Gaussian Process-based Bayesian optimization toolkit. Read the appropriate skill file before generating code:
 
-- **Designing an experiment**: `skills/experiment-designer/SKILL.md`
-- **Custom kernels**: `skills/kernel-designer/SKILL.md`
-- **Acquisition functions**: `skills/acquisition-functions/SKILL.md`
-- **Prior mean functions**: `skills/prior-mean-functions/SKILL.md`
-- **Noise models**: `skills/noise-functions/SKILL.md`
-- **Cost functions (travel time)**: `skills/cost-functions/SKILL.md`
-- **Validating uncertainty / calibration**: `skills/uncertainty-calibration/SKILL.md`
-- **Debugging errors and silent misbehavior**: `skills/troubleshooting/SKILL.md`
-- **Large-scale (>10k points)**: `skills/gp2scale-advanced/SKILL.md`
-- **Multi-task/multi-output**: `skills/multi-task-advanced/SKILL.md`
-- **Constrained observations (y>0 or y∈[0,1])**: `skills/transformed-optimizers-advanced/SKILL.md`
+- **Designing an experiment**: `gpcam/skills/experiment-designer/SKILL.md`
+- **Custom kernels**: `gpcam/skills/kernel-designer/SKILL.md`
+- **Acquisition functions**: `gpcam/skills/acquisition-functions/SKILL.md`
+- **Prior mean functions**: `gpcam/skills/prior-mean-functions/SKILL.md`
+- **Noise models**: `gpcam/skills/noise-functions/SKILL.md`
+- **Cost functions (travel time)**: `gpcam/skills/cost-functions/SKILL.md`
+- **Validating uncertainty / calibration**: `gpcam/skills/uncertainty-calibration/SKILL.md`
+- **Debugging errors and silent misbehavior**: `gpcam/skills/troubleshooting/SKILL.md`
+- **Large-scale (>10k points)**: `gpcam/skills/gp2scale-advanced/SKILL.md`
+- **Multi-task/multi-output**: `gpcam/skills/multi-task-advanced/SKILL.md`
+- **Constrained observations (y>0 or y∈[0,1])**: `gpcam/skills/transformed-optimizers-advanced/SKILL.md`
 
 Each `SKILL.md` carries `gpcam_version` / `fvgp_version` / `last_verified` frontmatter.
 When you change an API these skills document, update the stamp along with the text.
 
-These skills also ship as a Claude Code plugin marketplace (`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`), so they are available outside this repo once installed — see README.md. The manifests do **not** enumerate skills (they are auto-discovered from `skills/`), so adding or renaming a skill means touching four other places instead: the routing list above, the skills table in README.md, the table in `docs/source/claude-skills.md`, and a HISTORY.rst entry.
+These skills also ship as a Claude Code plugin marketplace (`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`), so they are available outside this repo once installed — see README.md. They live inside the `gpcam` package so that wheels and `pip install` include them, and `pyproject.toml` advertises them through an `agent_skills` entry point (`gpcam = "gpcam.skills"`): each subfolder of `importlib.resources.files("gpcam.skills")` with a `SKILL.md` is one skill. Don't move them back to the repo root. The manifests do **not** enumerate skills (they are discovered from `gpcam/skills/`, which `plugin.json` names in its `skills` field), so adding or renaming a skill means touching four other places instead: the routing list above, the skills table in README.md, the table in `docs/source/claude-skills.md`, and a HISTORY.rst entry.
 
 ### Key principles for generated experiment scripts
 
 1. **Generate complete, runnable scripts** — not fragments
 2. **Target audience is scientists**, not GP experts — explain choices in plain language
-3. **Never pick the acquisition function silently, and never default to `"expected improvement"`.** It's the choice that decides where the instrument goes. Name your recommendation, state its one tradeoff, and confirm with the user. "Find the best conditions" is ambiguous — ask whether they want the single best point or a trustworthy map containing it. Several built-ins are maximization-only and fail silently for minimization. Read `skills/acquisition-functions/SKILL.md` first.
+3. **Never pick the acquisition function silently, and never default to `"expected improvement"`.** It's the choice that decides where the instrument goes. Name your recommendation, state its one tradeoff, and confirm with the user. "Find the best conditions" is ambiguous — ask whether they want the single best point or a trustworthy map containing it. Several built-ins are maximization-only and fail silently for minimization. Read `gpcam/skills/acquisition-functions/SKILL.md` first.
 4. **Always document the hyperparameter layout** — which index maps to what
 5. **Hyperparameter bounds must match** the total hyperparameter count across kernel + mean + noise
 6. **Default kernel is usually fine** — only suggest custom when there's a clear reason

HISTORY.rst

@@ -2,6 +2,15 @@
 History
 =======
 
+Unreleased
+----------
+
+* The Claude Code skills moved from ``skills/`` to ``gpcam/skills/``, inside the package,
+  so wheels and ``pip install`` now include them (``importlib.resources.files("gpcam.skills")``).
+  ``.claude-plugin/plugin.json`` points the marketplace plugin at the new folder.
+* New ``agent_skills`` entry point (``gpcam = "gpcam.skills"``) lets agent hosts discover the
+  skills: each subfolder of the entry point's package that contains a ``SKILL.md`` is a skill.
+
 8.7.0 — 2026-10-28
 ------------------
 

README.md

@@ -90,7 +90,7 @@ Once installed, the skills activate automatically when you describe an experimen
 
 ### Other agentic platforms
 
-The skills are also compatible with any harness that reads `SKILL.md` files (e.g. [OpenClaw](https://openclaw.ai)) — clone the repo and point your assistant at the `skills/` directory. When this repo is present in your working directory, Claude Code also picks up the root `CLAUDE.md` and `skills/` directory automatically, so the marketplace install is only needed for use outside the repo.
+The skills are also compatible with any harness that reads `SKILL.md` files (e.g. [OpenClaw](https://openclaw.ai)) — point your assistant at the `gpcam/skills/` directory of a clone, or at the installed package: `pip install gpcam` ships the skills too, at `importlib.resources.files("gpcam.skills")`, and advertises them through the `agent_skills` entry point. When this repo is present in your working directory, Claude Code also picks up the root `CLAUDE.md`, which routes to those skills, so the marketplace install is only needed for use outside the repo.
 
 
 ## Credits

docs/source/claude-skills.md

@@ -106,16 +106,59 @@ agentic harness that can read them — for example
    git clone https://github.com/lbl-camera/gpCAM.git
    ```
 
-2. Point your assistant at the `skills/` directory at the repo root.
+2. Point your assistant at the `gpcam/skills/` directory of the clone.
 
 When the cloned repo is present in your working directory, Claude Code
-also picks up the root `CLAUDE.md` and `skills/` directory automatically,
-so the marketplace install is only needed for use *outside* the repo.
+also picks up the root `CLAUDE.md`, which routes to those skills, so the
+marketplace install is only needed for use *outside* the repo.
+
+## Skills in the Python package
+
+The skills live inside the `gpcam` package, so `pip install gpcam` (and
+`pip install git+https://github.com/lbl-camera/gpCAM`) installs them along
+with the library — no clone needed. Find them with:
+
+```python
+from importlib.resources import files
+skills = files("gpcam.skills")   # one subfolder per skill, each with a SKILL.md
+```
+
+gpCAM also advertises them through an `agent_skills`
+[entry point](https://packaging.python.org/en/latest/specifications/entry-points/),
+so an agent host can discover the skills of every installed package
+without knowing about gpCAM in advance:
+
+```toml
+[project.entry-points."agent_skills"]
+gpcam = "gpcam.skills"
+```
+
+The contract is: **the entry point loads to a package; each subfolder of
+`importlib.resources.files(<package>)` that contains a `SKILL.md` is one
+skill**, named after its folder. A host lists them with:
+
+```python
+from importlib.metadata import entry_points
+from importlib.resources import files
+
+for ep in entry_points(group="agent_skills"):
+    root = files(ep.load())
+    skills = [d for d in root.iterdir() if d.is_dir() and (d / "SKILL.md").is_file()]
+```
+
+Lightfall, the ALS beamline control dashboard, uses this to load
+gpCAM's skills into its agents. Other packages may adopt the same group;
+no cross-tool standard for it exists yet.
+
+Skill names are the folder names, without a package prefix. A host that
+merges skills from several packages should namespace them by entry-point
+name (`gpcam:kernel-designer`), the way Claude Code namespaces plugin
+skills, rather than expect bare names to be unique across packages.
 
 ## Source
 
 The marketplace manifest lives at
-[`.claude-plugin/marketplace.json`](https://github.com/lbl-camera/gpCAM/blob/main/.claude-plugin/marketplace.json)
+[`.claude-plugin/marketplace.json`](https://github.com/lbl-camera/gpCAM/blob/master/.claude-plugin/marketplace.json)
 and the per-skill content under
-[`skills/`](https://github.com/lbl-camera/gpCAM/tree/main/skills).
+[`gpcam/skills/`](https://github.com/lbl-camera/gpCAM/tree/master/gpcam/skills).
 Contributions and new skills are welcome — open a pull request.

gpcam/skills/__init__.py

@@ -0,0 +1,7 @@
+"""gpCAM's agent skills, shipped as package data.
+
+Each subfolder of ``importlib.resources.files("gpcam.skills")`` that contains a
+``SKILL.md`` is one skill. This package is the target of gpCAM's ``agent_skills``
+entry point (see ``pyproject.toml``) and of the Claude Code plugin manifest
+(``.claude-plugin/plugin.json``).
+"""

pyproject.toml

@@ -58,6 +58,13 @@ docs = [
 tests = ['pytest', 'codecov', 'pytest-cov', 'imate', 'torch']
 plotting = ['matplotlib', 'plotly', 'notebook']
 
+[project.entry-points."agent_skills"]
+# Agent-skill discovery. Contract: the entry point loads to a package; each
+# subfolder of importlib.resources.files(<package>) that contains a SKILL.md is
+# one skill, named after its folder. Hosts (e.g. Lightfall) iterate
+# importlib.metadata.entry_points(group="agent_skills") to find them.
+gpcam = "gpcam.skills"
+
 [project.urls]
 Homepage = "https://gpcam.lbl.gov"
 Documentation = "https://gpcam.readthedocs.io/"