1 files changed, 124 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..386772b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# 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