From c596038adc7cdbd64988e61fee856d533b58c25d Mon Sep 17 00:00:00 2001 From: "Simen A. W. Olsen" Date: Sun, 25 Oct 2026 12:41:28 +0100 Subject: feat: skills, a package manager for agent skills --- skill/skills/SKILL.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 skill/skills/SKILL.md (limited to 'skill') diff --git a/skill/skills/SKILL.md b/skill/skills/SKILL.md new file mode 100644 index 0000000..14f611c --- /dev/null +++ b/skill/skills/SKILL.md @@ -0,0 +1,50 @@ +--- +name: skills +description: Install, update, list and remove agent skills with the `skills` CLI, which fetches skills from git repositories, locks them to a commit and links them into Claude Code, Codex and OpenCode. Use when the user wants to add a skill from a repository, update or remove installed skills, see which skills are installed and where they came from, or set skills up on a new machine. +allowed-tools: Bash(skills *), Bash(skills) +--- + +# skills + +`skills` is a package manager for agent skills. A skill is a directory holding +a `SKILL.md`; a source is a git repository holding one or more skills. + +What the user added is in a manifest, `skills.json`, and the exact commit of +each source in `skills.lock` next to it. Find them with `skills list`, which +prints the manifest path when it is empty. `--manifest ` or +`$SKILLS_MANIFEST` points at another one. + +## Commands + +| Task | Command | +|---|---| +| See sources, skills and install state | `skills list` (`--json` for scripts) | +| Add every skill in a repository | `skills add owner/repo` | +| Add some skills | `skills add owner/repo --skill pdf --skill xlsx` | +| Follow a branch or tag, or pin a commit | `skills add owner/repo#v1.2.0` | +| Name the source | `skills add owner/repo --name mine` | +| Move to the newest commits | `skills update [source...]` | +| Remove a source and its skills | `skills remove ...` | +| Install exactly what is locked (new machine) | `skills install` | + +Sources are `owner/repo` (GitHub), any git URL, `user@host:path`, or a local +path. Private repositories work as long as `git ls-remote ` works. + +## How to work with it + +- Run `skills list` first; source names, not skill names, are what `update` + and `remove` take. +- A source without `--skill` follows the repository: skills it gains on + update are installed too. Mention this when adding a large collection. +- `skills` only touches symlinks it created. If it reports a conflict, an + existing directory has the skill's name; ask the user before moving it. +- Exit codes: 0 success, 1 failure, 2 invalid usage, 130 interrupted. + +## Managed by Nix + +When `SKILLS_MANAGED_BY` is set (the home-manager module sets it to +`home-manager`), `skills` edits the manifest and lock and fetches sources into +the Nix store, but does not link anything. Tell the user to apply their +home-manager configuration (for example `home-manager switch` or their +`darwin-rebuild`/`nixos-rebuild` alias) for the change to take effect, and +that the manifest and lock are files in their configuration to commit. -- cgit v1.3.1