beaker-setup

Beaker setup

Turn the repository's real LLM or agent task into a repository optimization spec. Find the application entrypoint, candidate source, model call, scorer, and labeled data before completing the integration. Finish with a passing local structural smoke check when real labeled examples are available; launch remotely only when the developer requests it.

Load the installed skill first

When the developer asks to install or update this skill, finish that command before loading and following the newly installed copy. Never install or update the skill in parallel with loading it. If this session loaded an older copy before replacement, reload the installed skill; when the agent host cannot refresh skills in place, start a new agent session instead of continuing with stale instructions. A user who already has the requested version installed can load it normally without reinstalling it.

Version check

This skill (0.4.9) is written for beaker-sdk 0.4.9. The skill and the SDK are released in lockstep with the same version number, so any difference between them means one side is stale. Before the happy path, run beaker --version (or uvx --from 'beaker-sdk>=0.4.9' beaker --version while Beaker is not yet installed in the project). If the installed CLI is older than 0.4.9, or does not recognize --version, upgrade beaker-sdk through the project's development-dependency workflow before continuing; older CLIs may lack commands or flags this skill relies on. If the CLI is newer than 0.4.9, this skill is stale: run npx skills update beaker-setup and npx skills update beaker-usage, then reload the skill as described above. Do not work around a mismatch by guessing at CLI behavior.

Happy path

Follow this order. The rest of this skill is constraints and recovery.

1. beaker auth status (run beaker login only if it fails), then beaker agent list --json. Use uvx --from beaker-sdk beaker ... until the project dependency is installed.
2. Identify the package or service being optimized, not the Git root: in a monorepo that is the directory holding the task's own pyproject.toml.
3. Select that project's existing Beaker config, or enter the project root and run beaker init.
4. Check the generated spec.source_dir right away: it must be the project's Git-root-relative directory, for example services/invoices, and "." only when the project is the Git root. Fix it immediately if it disagrees; do not wait for a migration hint.
5. Install the beaker-sdk dependency command beaker init printed, in the project's development/tooling dependency group.
6. After initial discovery, ask all currently known unresolved decisions together, such as which metric to optimize, the labeled-data source, quick-start versus full dataset size, agent name, judge model, or required credentials. Do not wait for discovery to be exhaustive, and continue independent discovery and implementation while the developer responds. Batching is best effort: if later discovery reveals another required decision, ask it then rather than guessing or delaying current work.
7. Replace every TODO(beaker) in the spec and wire the real model call.
8. beaker agent setup "<Agent Name>" (add --spec-id <id> when the config has several specs). Setup records the agent key in agent_key in the selected YAML. A name the developer supplied is approval; do not ask again.
9. Relay newly discovered GitHub, labeled-data, and credential actions as soon as beaker onboarding status reports them; ask the developer to begin those actions immediately, then continue independent agent-owned work.
10. Upload or select the labeled dataset, retain its immutable name@revision or artifact id, pass that same selector explicitly to smoke and launch, confirm required hosted environment values, and validate with beaker run smoke --strict. Do not commit an organization-specific dataset selector to YAML by default; a YAML dataset default is optional.
11. Commit and push once, after the selected config and dataset are final, to beaker/<YYYYMMDD-HHMM>-<agent-name>.
12. The first hosted run is a plain beaker run trigger (Beaker agent, dataset, optional --ref). Do not pass --optimization-model unless the developer explicitly asked to compare specific models. As soon as it starts, tell the developer that repository setup is finished, name the run state, and make clear that any remaining wait is for Beaker's hosted run rather than more integration work.
13. Run beaker onboarding status after each completed step above, not after read-only probes.