cuga-skills

Curated skills for CUGA agents, plus a CLI that installs them into .cuga/skills.

uvx cuga-skills add            # pick from the catalog interactively
uvx cuga-skills list           # see what's available and what's installed

CUGA discovers skills from .cuga/skills/**/SKILL.md by default, so an installed skill is available the next time the agent starts — no config change needed.

Commands

Options: --dir PATH to install somewhere other than ./.cuga/skills, -g/--global for ~/.config/cuga/skills, --ref REF to install from a specific git ref of this repo, --force to overwrite.

Installed skills are recorded in .cuga/skills-lock.json (next to the install directory), including the content hash of each skill so list can tell you when a skill was changed locally or updated upstream.

Catalog

Contributing a skill

Open a PR adding skills/<name>/SKILL.md. That is the only publishing path — there is no registry service and no account to create.

skills/my-skill/
  SKILL.md          # required
  scripts/          # optional companion files, copied as-is

SKILL.md starts with YAML frontmatter:

---
name: my-skill              # must match the directory name
description: Use when ...   # shown in the catalog listing; say when to use it
requirements:               # optional; CUGA installs these in its sandbox
  - python-pptx
tags:                       # optional
  - documents
---

# My skill

Instructions for the agent...

Then regenerate the index and run the tests:

uv sync
uv run cuga-skills build-index
uv run pytest

CI re-runs build-index --check, so a PR with a stale skills/index.json fails.

What makes a good skill here

This catalog is for end-user productivity — documents, data, research, reporting. Skills for building CUGA agents (adding tools, authoring policies, debugging trajectories) belong in cuga-harness-kit instead.

A useful description says when to use the skill, not what it is: reviewers use that line to decide whether the agent will pick the skill up at the right moment.

How installation works

1. Fetch skills/index.json from this repo (cached for an hour under ~/.cache/cuga-skills).
2. Download the repo tarball for --ref and extract only the requested skill folders.
3. Verify each folder's content hash against the index; a mismatch aborts before anything is written.
4. Copy into the target directory and record it in skills-lock.json.

No server, no auth. If GitHub is unreachable, the CLI falls back to the catalog copy bundled in the installed wheel.

Releasing the CLI

Bump version in pyproject.toml, tag vX.Y.Z, push the tag — release.yml builds with uv build and publishes via PyPI trusted publishing. Adding or editing a skill needs no release: the CLI fetches skills from the git ref at install time.

License

Apache-2.0