cuga-harness-kit

Skills that teach Claude Code, Cursor, Codex, and Bob how to install, launch, and build with cuga — the open-source generalist agent framework.

Assistant quickstart

Paste this into Claude Code, Cursor, Codex, or Bob from the project folder you want to set up:

Run `uv tool install --upgrade cuga-harness-kit`, then `cuga-harness-kit init` in this folder. Read and follow the full `using-cuga` skill.

This prompt installs the latest published release from PyPI.

The assistant will install this kit, scaffold the cuga guidance files, then follow using-cuga:

1. Inspect the existing project and reuse any established provider, execution mode, and successful checks.
2. Configure your LLM provider and verify a model request. Install CUGA for a local SDK app or local server when needed; use existing server-side configuration for a remote managed-server client.
3. Explain what you want to build and choose SDK embedding (usually your own app/UI) or a managed CUGA server (Manage UI, draft/publish config, HTTP clients). A custom UI can use either path.
4. Ask "help me build a cuga tool" or "how do I add a policy" when you're ready to build.

Manual install

No git clone, no marketplace install:

uv tool install cuga-harness-kit
(if update: uv pip install -e . --reinstall-package cuga-harness-kit)
cuga-harness-kit init

If you're installing inside an already-active virtualenv instead of as a CLI tool, use uv pip install cuga-harness-kit.

Run init from an empty new project you're starting from scratch, or from inside an existing cuga checkout — either way it writes the same skill set into the current directory:

• .claude/skills/<name>/SKILL.md — auto-discovered by Claude Code.
• .cursor/skills/<skill-name>/SKILL.md — native Cursor skills; directory names match each skill's frontmatter name (for example cuga-build-agent or using-cuga).
• AGENTS.md — read by Codex. Re-running init only touches the managed block, so it won't clobber the rest of the file.
• .bob/skills/<name>/SKILL.md — auto-discovered by IBM Bob.
• docs/cuga-env-api-keys.md — local reference for .env API-key setup.

What's included

Each is authored once as a SKILL.md under src/cuga_harness_kit/builder-skills/, then used verbatim for Claude, Cursor and Bob or rendered into Codex AGENTS.md sections at init time.

CLI

cuga-harness-kit init [--targets claude,cursor,codex,bob] [--force] [--dry-run]
cuga-harness-kit update   # alias for `init --force`

• --targets — comma-separated subset of claude, cursor, codex, bob (default: all four).
• --force — overwrite scaffolded files that already exist and differ (default: skip and report).
• --dry-run — print what would be written without touching disk.

Migration pipeline (optional, claude/bob only)

Besides the guidance skills above, this kit can also scaffold cuga-migrator — a separate tool that converts an existing agent system into a cuga SDK implementation, via a 5-stage pipeline (analyst → implementer → test_writer → evaluator → debugger). It's opt-in and exclusive: it replaces the guidance skills for that run rather than adding to them.

cuga-harness-kit init --targets claude --migration   # or --targets bob

This scaffolds the migration skills/agents, launch scripts, cuga-templates/, and migration_from//migration_to/, then clones the cuga SDK for the pipeline to reference. Once scaffolded, three more subcommands become available, grouped under migrate:

cuga-harness-kit migrate source_sync <source-name>
cuga-harness-kit migrate cuga_sync
cuga-harness-kit migrate run <source-name> <target-name>

You can also just ask Claude Code / Bob directly, in natural language. See the scaffolded kit's own README.md for the full walkthrough. Useful flags: --skip-sdk (don't clone the SDK), --cuga-ref <branch-or-tag> (pin a version).

Updating

New releases of cuga-harness-kit ship improved skill content. To pick it up in a project that already ran init:

uv tool upgrade cuga-harness-kit
cuga-harness-kit update

update overwrites scaffolded files unconditionally — if you hand-edited one to customize it, update will clobber that edit (there's no diff/merge, except for AGENTS.md's managed block). Copy customizations out first if you want to keep them.

Cursor rules to skills

Starting with 0.2.0, the Cursor target writes native skills instead of .mdc rules. To migrate an existing project after upgrading the package:

cuga-harness-kit init --targets cursor

After each native skill is installed, byte-identical generated .cursor/rules/cuga-<name>.mdc files are removed. Older or edited rules (including newline-only differences) are moved to inactive .mdc.bak files (or .mdc.bak.1, etc. when a backup already exists); the CLI reports their paths so you can transfer customizations into the new skills. Unrelated rules are left alone. Legacy rules reached through a symlinked file, .cursor, or rules directory are retained and reported for manual migration.

init preserves an existing native skill that differs, and leaves its legacy rule active until you resolve the conflict. update --targets cursor replaces differing native skills as usual. Use init --targets cursor --dry-run to preview writes, removals and backups without changing files.

cuga project setup

When the generated skills help you install cuga in an app, they default to a uv project so dependencies are captured in pyproject.toml:

uv init my-cuga-app
cd my-cuga-app
uv add cuga

The SDK configures an agent in your Python process. The managed server reads per-agent draft and published versions from its config store. SDK tools/policies and .cuga/ files do not automatically update managed config; use the managed-server skill for that workflow.

For API keys and provider settings, see docs/env-api-keys.md.

Development

uv sync
uv run pytest

For the runtime-backed builder checks and their coverage limits, see builder validation.