Skip to content

# The Library

The library is a personal shelf for things you've downloaded but haven't necessarily switched on. It lives under your global config directory at `~/.config/swival/library/` (or `$XDG_CONFIG_HOME/swival/library/`), and the agent never loads anything from it directly. You stage a collection there once, look it over, and then install the pieces you actually want into a project or into your global active set.

Today the library holds skills, under `library/skills/`. The name was chosen with room to grow: it is meant to become the staging area for other global resources you might pull in from elsewhere and selectively add to a project later. For now this page is about skills, which is the part that exists.

## Why A Staging Shelf

There are three places a skill can end up. Two are active, meaning the agent discovers and can load them:

- `.swival/skills/` is active in this project only.
- `~/.config/swival/skills/` is active in every project.

The third is the library:

- `~/.config/swival/library/skills/` is staged, not active. The agent does not see these.

The split exists so that fetching a third party's repository and turning their instructions loose in every session are two separate, deliberate steps. You can download a collection, read the `SKILL.md` files at your leisure, and only then promote the ones you trust. Nothing in the library influences a run until you install it somewhere active.

The library is organized two levels deep: `library/skills/<collection>/<skill>/SKILL.md`. A collection is just the set of skills that came from one source, named after the repository it was cloned from unless you rename it.

## The Commands

    swival skills add    [--global] [--as NAME] [--ref REF] [--force] <name-or-URL>
    swival skills delete [--global] [--library] <name>
    swival skills list   [--library]

The examples below all use `DietrichGebert/ponytail`, a repository whose top-level `skills/` directory ships six skills (`ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`).

## Staging A Collection

Point `add --global` at a git repository and Swival shallow-clones it, finds the `skills/` directory, and copies what it finds into the library. It does not activate anything.

    swival skills add --global https://github.com/DietrichGebert/ponytail

    Staged 6 skill(s) into the library (~/.config/swival/library/skills/ponytail):
      ponytail, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help, ponytail-review
    Run 'swival skills add ponytail' to install them into this project,
    or 'swival skills add --global ponytail' to install them globally.

The collection takes its name from the repository (`ponytail`). Override that with `--as`, which is handy when you want to stage the same repo at two different points in time, or just prefer a shorter name:

    swival skills add --global --as pony https://github.com/DietrichGebert/ponytail

Pin a specific branch, tag, or commit with `--ref` (or append `#ref` to the URL). This is the safe way to depend on a third party: a moving `main` can change under you, a pinned commit cannot.

    swival skills add --global --as pony-stable --ref main https://github.com/DietrichGebert/ponytail

A repository whose `SKILL.md` sits at the root, rather than under `skills/`, is treated as a single skill and staged as a one-skill collection.

## Listing What You Have

`list --library` shows the staged collections, where each came from, and the skills inside them. If a collection was pinned, the ref is shown after the URL.

    swival skills list --library

    skills library (~/.config/swival/library/skills):
      pony  [https://github.com/DietrichGebert/ponytail]
        ponytail
        ponytail-audit
        ponytail-debt
        ponytail-gain
        ponytail-help
        ponytail-review
      pony-stable  [https://github.com/DietrichGebert/ponytail @ main]
        ...

Plain `list` (no flag) shows the active project and global skills instead, which is the set the agent will actually load.

## Promoting From The Library

Once a collection is staged, install from it by name. Without `--global` the skill lands in `.swival/skills/` for the current project; with `--global` it lands in your global active set.

    swival skills add ponytail-review            # one skill, into this project
    swival skills add --global ponytail-gain     # one skill, active everywhere
    swival skills add ponytail                   # the whole collection, into this project

Installing a single skill reports exactly what moved:

    Installed 1 skill(s) into this project (.swival/skills): ponytail-review

Installing a collection where one skill is already present skips the duplicate and installs the rest:

    ⚠ Warning: skill 'ponytail-review' already exists in .swival/skills; use --force to replace
    Installed 5 skill(s) into this project (.swival/skills): ponytail, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help

Pass `--force` to overwrite instead of skip:

    swival skills add --force ponytail

If the same skill name exists in more than one staged collection, a bare name is ambiguous and Swival refuses rather than guess:

    Error: skill 'ponytail-review' is ambiguous across collections:
    pony/ponytail-review, pony-stable/ponytail-review; disambiguate with 'collection/skill'

Spell out the collection to resolve it:

    swival skills add pony/ponytail-review

## Skipping The Library

If you already trust a repository and don't want a review step, point `add` at the URL without `--global`. Swival clones it and installs straight into the current project, no staging:

    swival skills add https://github.com/DietrichGebert/ponytail

    Installed 6 skill(s) into this project (.swival/skills): ponytail, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help, ponytail-review

This is the shortcut. The staged flow exists for when you want to look before you leap.

## Removing Things

Plain `delete` only ever touches active skills, never the library. You address an active skill by name:

    swival skills delete ponytail-debt           # from .swival/skills/
    swival skills delete --global ponytail-gain  # from ~/.config/swival/skills/

To remove something from the library you must say so with `--library`. You can drop one skill out of a collection, or the whole collection at once:

    swival skills delete --library pony/ponytail-help   # one skill
    swival skills delete --library pony                 # the whole collection

Deletion happens immediately, with no confirmation prompt, but Swival always prints exactly what it removed:

    Removed skill ponytail/ponytail-help from the library
    Removed collection 'pony' from the library

## A Note On Safety

Cloning and staging never execute anything. Helper scripts and `SKILL.star` metaskills that ship inside a skill sit inert until you both install the skill and, for external metaskills, pass `--metaskills all`. Swival flags any installed skill that carries a `SKILL.star`, so a downloaded metaskill can't quietly become runnable. Clones run with credential prompts disabled, HTTP redirects refused, and non-git protocols blocked, and any URL that resolves to a private or internal address is rejected outright.

For everything about authoring skills, discovery precedence, and progressive disclosure, see the Skills page. For the metaskill format and host API, see Agent MetaSKILLs.