skills

A package manager for agent skills: 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.

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

go install simenandre.no/skills@latest

With Nix:

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

Use

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:

{
  "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:

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

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

License

MIT