Agent Skills#
Osprey ships twelve agent skills — packaged, step-by-step instructions that a coding agent picks up automatically when a task matches their description. Instead of re-explaining the contribution workflow or the release process in every session, you install them once and the agent follows the project’s own playbooks.
All twelve travel together in one plugin, osprey, published from the root of
the als-apg/osprey repository. Claude Code and Codex install it from there
with two commands each.
Install in Claude Code#
claude plugin marketplace add als-apg/osprey --sparse .claude-plugin plugins
claude plugin install osprey@osprey
Both commands need Claude Code 2.1.228 or newer.
The first command registers the marketplace. The second installs the plugin at user scope, which is the default, so the skills are available in every session that reads user settings.
--sparse keeps the working checkout to the manifest and plugin directories.
It does not reduce how much git transfers.
Invoke a skill by its namespaced name, for example /osprey:contribute.
Warning
Registering a marketplace named osprey from a second source — a local
clone, say — silently repoints the name to that source. To restore it, run
the first command above again to re-add the marketplace from
als-apg/osprey.
Inside a deployment repository#
Install the plugin a second time at project scope:
claude plugin install osprey@osprey --scope project
Sessions launched by osprey chat and by the web terminal run with
--setting-sources project. Those sessions cannot see user-scope plugins,
so without the project-scope install the skills never load there. The install
writes enabledPlugins into the repository’s .claude/settings.json.
Updating#
claude plugin marketplace update osprey
claude plugin update osprey@osprey
The first command refreshes the marketplace listing; the second installs the
version it now points at. Restart the session to pick it up. Add
--scope project to the second command to update a project-scope install.
Iterating on a skill locally#
From a checkout of the repository, load the plugin straight off the working tree instead of installing it:
claude --plugin-dir plugins/osprey
The session reads the skills from plugins/osprey/skills/, so you can edit a
SKILL.md and start a new session to try it.
Install in Codex#
codex plugin marketplace add als-apg/osprey --sparse .agents/plugins --sparse plugins
codex plugin add osprey@osprey
Codex invokes a skill with a leading $, for example $contribute. The
skills themselves are the same files the Claude Code plugin serves.
Command syntax: learn.chatgpt.com/docs/developer-commands.
The twelve skills#
Skill |
What it does |
|---|---|
|
Osprey’s design and architecture principles, and the anti-pattern each one prevents. Consult it before adding a config knob, a new abstraction, or anything touching hardware-write safety. |
|
Takes a working-tree change to a merged PR on |
|
Runs the check command’s tiers — quick, full, quick scoped to the diff — at the gate that matches what you are about to do. |
|
Walks a maintainer through a CalVer release: the release-notes PR, the tag, and verifying the automated PyPI publish. |
|
The guided setup, as a conversation: installs Osprey if it is missing, inventories what exists, and sets up or migrates a deployment for an accelerator, beamline, or detector one confirmed card at a time. |
|
Resolves what the facility build flags, with the maintainer of the
facility repository: starts from |
|
Investigates whether something a facility needs is an Osprey gap, a
deployment gap, or already supported; judges whether the fix is
mechanical or architectural; drafts the write-up to file or to branch
from. |
|
Authors a themed web-terminal panel that passes the panel validator. |
|
Builds an app — panel, backend and agent tools under one |
|
Finds where the generated project, the shipped prompts, the runtime messages, or a pinned version say something the code no longer does, proves it, and writes a report the maintainer rules on. Report only. |
|
Proves the pages under |
|
Gates every new or changed test on what regression it catches and why existing coverage misses it, and audits existing tests for ones that re-assert source, duplicate stronger proof, or keep test-only production seams alive. A campaign mode prunes one subsystem’s whole test surface. |
In Codex the same twelve are $design-philosophy, $contribute,
$pre-commit, $release, $setup, $facility-review,
$upstream-scout, $panel, $build-app, $housekeeping,
$doc-sync, and $test-audit.
The skills route to each other: /osprey:contribute hands a standalone
validation run to /osprey:pre-commit and a release to /osprey:release;
/osprey:release runs /osprey:housekeeping and /osprey:doc-sync as
advisory steps before the release-notes PR, /osprey:housekeeping hands
doc-page items to /osprey:doc-sync, /osprey:setup launches
/osprey:upstream-scout in the background, and the scout’s branch path hands
the implementation to /osprey:contribute, as /osprey:test-audit does
with a finished audit.
The workflow behind each one is documented on its own page:
Git and GitHub Workflow — the contribution journey
/osprey:contributefollows.Development Setup — the checks
/osprey:pre-commitruns.Guided Facility Setup — the deployer-facing page, written for someone standing up a deployment.
Describe your facility — the facility tree, the fixes and the build
/osprey:facility-reviewworks from.Panels — the panel contract, with the extension seam on Extending Osprey.
Build Your Own App — the app contract
/osprey:build-appbuilds to.