# skills

A package manager for [agent skills](https://agentskills.io): directories
holding a `SKILL.md` that teach Claude Code, Codex, OpenCode and other agents
how to do something.

`skills` installs them from any git repository, locks each one to a commit
and links it into every agent you use. The skills you added go in a manifest
and the exact commits in a lock file next to it, so committing both gives you
the same skills on every machine.

```console
$ skills add anthropics/skills --skill pdf --skill xlsx
Added skills at dbd4588: pdf, xlsx
Installed pdf, xlsx for claude, codex

$ skills list
skills    dbd4588    anthropics/skills
  pdf     installed  skills/pdf
  xlsx    installed  skills/xlsx

$ skills update
skills is up to date at dbd4588
All skills are installed for claude, codex
```

## Install

You need git. With Go:

```sh
go install simenandre.no/skills@latest
```

With Nix:

```sh
nix profile install git+https://git.simenandre.no/skills
```

## Use

```sh
skills add owner/repo                 # every skill in a GitHub repository
skills add owner/repo --skill pdf     # just one
skills add owner/repo#v1.2.0          # follow a tag or branch, or pin a commit
skills add git@host:me/skills.git     # any git URL, including private ones
skills list                           # what is installed, from where, for whom
skills update [source...]             # move to the newest commits
skills remove <source>...             # uninstall
skills install                        # install exactly what is locked
```

`skills <command> --help` explains each command, with examples.

### Where things go

| What | Where |
|---|---|
| Manifest | `--manifest`, else `$SKILLS_MANIFEST`, else `$XDG_CONFIG_HOME/skills/skills.json` |
| Lock | `skills.lock`, next to the manifest |
| Checkouts | `$XDG_DATA_HOME/skills` |
| Installed skills | symlinks in each agent's skills directory |

Agents: `claude` (`$CLAUDE_CONFIG_DIR` or `~/.claude`), `codex` (`$CODEX_HOME`
or `~/.codex`) and `opencode` (`$XDG_CONFIG_HOME/opencode`). By default
`skills` installs into every one of them that exists on the machine; to choose,
list them in the manifest:

```json
{
  "agents": ["claude"],
  "sources": { "...": {} }
}
```

`skills` only ever replaces or removes symlinks it created, so skills you
installed some other way are left alone. If one is in the way, it tells you.

### Scripts

`skills list --json` prints machine-readable output. Progress goes to stderr,
and only to a terminal; `--quiet` silences everything but errors. Exit codes:
0 success, 1 failure, 2 invalid usage, 130 interrupted.

## home-manager

The flake has a home-manager module that installs the locked skills itself,
so they are part of your configuration like anything else:

```nix
{
  inputs.skills.url = "git+https://git.simenandre.no/skills";

  # in your home-manager configuration
  imports = [ inputs.skills.homeManagerModules.default ];
  programs.skills = {
    enable = true;
    lockFile = ./skills.lock;
    # Lets `skills add` and `skills update` edit this file in your checkout.
    manifest = "/home/me/dotfiles/skills.json";
    agents = [ "claude" "codex" ];
  };
}
```

The module sets `SKILLS_MANAGED_BY=home-manager`. `skills` then edits the
manifest and lock, fetches sources into the Nix store as you, and leaves the
installing to your next switch. Fetching as you matters for private
repositories: Nix finds them already in the store by their hash, even when
root evaluates your configuration without your SSH keys. On a new machine, run
`skills install` before your first switch for the same reason.

## Agent skill

`skill/skills` teaches agents to use this CLI. Install it with:

```sh
skills add https://git.simenandre.no/skills --skill skills
```

## License

MIT