feat: skills, a package manager for agent skillsHEADv0.1.0main

1 files changed, 50 insertions, 0 deletions

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 <path>` 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 <source>...` |
+| 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 <url>` 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.