Metadata-Version: 2.4
Name: cuga-skills
Version: 0.1.0
Summary: Curated skill marketplace for CUGA agents — browse and install SKILL.md folders into .cuga/skills.
Project-URL: Homepage, https://github.com/cuga-project/cuga-skills
License-Expression: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: questionary>=2.0.1
Requires-Dist: typer>=0.15.3
Description-Content-Type: text/markdown

# cuga-skills

Curated skills for [CUGA](https://github.com/cuga-project/cuga-agent) agents, plus a CLI that installs them into `.cuga/skills`.

```bash
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

| Command | What it does |
| --- | --- |
| `cuga-skills list [QUERY]` | Show the catalog, marking installed / modified / update available |
| `cuga-skills add [NAMES...]` | Install skills. With no names, opens a multi-select picker |
| `cuga-skills update [NAMES...]` | Re-install. With no names, updates everything installed |
| `cuga-skills remove NAME` | Delete an installed skill |

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

| Skill | What it does |
| --- | --- |
| `hello-world` | Smallest valid skill — checks that skill loading and code execution work |
| `csv-summary` | Profiles a CSV: column types, missing values, ranges, frequent values |
| `slide-outline` | Turns a markdown outline into a `.pptx` |

## 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:

```markdown
---
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:

```bash
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](https://github.com/cuga-project/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
