@invariant.guru/cli 0.6.8 → 0.6.9

package/README.md

@@ -46,7 +46,7 @@ Supported targets: `claude`, `codex`, `cursor`, `aider`, `copilot`.
 
 ### 2. `invariant install` — pull a package
 
-Packages come from the registry or straight from GitHub. Installing caches the package **and** activates its items.
+Packages come from a GitHub repository, from the [skills.sh](https://www.skills.sh) catalogue, or from the registry. Installing caches the package **and** activates its items.
 
 ```bash
 # From GitHub (owner/repo, optional #ref)
@@ -55,6 +55,12 @@ invariant install github:invariant-guru/inv-nest-clean-architecture
 # Pin a branch or tag
 invariant install github:invariant-guru/inv-nest-clean-architecture#main
 
+# From skills.sh — the repository is cached, that one skill is activated
+invariant install skills:vercel-labs/skills/find-skills
+
+# …or the whole catalogue source, activating every skill it ships
+invariant install skills:anthropics/skills
+
 # From the registry (same package, published name)
 invariant install nest-clean-architecture
 ```
@@ -259,11 +265,13 @@ invariant init --hybrid
 
 ### `invariant install [packages...]`
 
-Install packages from the registry or GitHub and activate their items. If the package already has curated `active` entries in `invariant.json`, exactly those are restored; otherwise all items are added.
+Install packages from GitHub, skills.sh or the registry and activate their items. If the package already has curated `active` entries in `invariant.json`, exactly those are restored; otherwise all items are added.
 
 ```bash
 invariant install github:invariant-guru/inv-nest-clean-architecture
 invariant install github:invariant-guru/inv-nest-clean-architecture#v1.2.0
+invariant install skills:vercel-labs/skills/find-skills
+invariant install https://www.skills.sh/vercel-labs/skills/find-skills
 invariant install nest-clean-architecture
 invariant install nest-clean-architecture@1.0.0
 
@@ -282,6 +290,38 @@ Source syntax:
 | `name@version` | Registry package, pinned version |
 | `github:owner/repo` | GitHub repo, default branch |
 | `github:owner/repo#ref` | GitHub repo at a branch, tag, or commit |
+| `skills:owner/repo` | A skills.sh source, whole. Every skill it ships is cached and activated |
+| `skills:owner/repo/skill` | The same source, cached whole, with **only that skill** activated |
+| `https://www.skills.sh/owner/repo/skill` | The page URL, accepted as-is |
+
+#### Installing from skills.sh
+
+[skills.sh](https://www.skills.sh) indexes ~9,700 agent skills, all of them
+living in public GitHub repositories. Installing from it fetches **the
+repository**, because that is what a package is here — one source, many items —
+and then activates the one skill you asked for. `invariant add` turns the rest
+on later, without a second download.
+
+Two consequences worth knowing before the first install:
+
+- **The package is `@owner/repo`.** Half the catalogue's repositories are called
+  `skills`; the owner is what keeps `@vercel-labs/skills` and
+  `@anthropics/skills` apart.
+- **The skill lands under its package-prefixed name** — `find-skills` from
+  `vercel-labs/skills` installs to
+  `.agents/skills/vercel-labs-skills-find-skills`, mirrored into `.claude/`.
+  That is [ADR-024](docs/ADR.md) working as designed; see
+  [docs/package-naming.md](docs/package-naming.md).
+
+Skill folders are copied whole — `scripts/`, `references/`, licences and all.
+Binary files and anything over 256 KB are skipped and named in the output.
+Nothing is executed at install time.
+
+Two environment variables exist for testing and for self-hosted mirrors:
+`INVARIANT_SKILLS_API_URL` (default `https://www.skills.sh`) and
+`INVARIANT_SKILLS_DOWNLOAD_URL` (default `https://skills.sh`). `GITHUB_TOKEN` /
+`GH_TOKEN`, when set, is used for the repository metadata call that supplies
+star counts.
 
 | Option | Description |
 |--------|-------------|
@@ -564,8 +604,15 @@ runs. It never writes `invariant.json` itself.
   like; the bar at the bottom shows what will run, and **Apply** issues one
   `remove` and one `add` for the whole batch. Optionally a `sync` after.
 - **Install** takes a GitHub repository (the default — `owner/repo`, or a pasted
-  URL, plus an optional ref) or a registry name, and previews the exact
-  `invariant install …` line including `--no-add` and `--sync`.
+  URL, plus an optional ref) or a skills.sh skill (search as you type, or paste
+  `owner/repo/skill`), and previews the exact `invariant install …` line
+  including `--no-add` and `--sync`.
+- **Browse skills** opens the catalogue at `/packages/skills`: ranked by
+  Popular / Trending / Hot, searchable, with a preview pane carrying the
+  install count, the weekly trend, the GitHub stars, the licence, the file list
+  and the rendered SKILL.md — plus the path the skill will actually occupy on
+  disk, before you install it. `/` focuses search, `j`/`k` move, `Esc` goes
+  back.
 - **Sync** runs from the top bar, with a **Check only** dry run that reports
   drift the way CI does.
 - **A package the config declares but this checkout never installed** shows as
@@ -722,18 +769,42 @@ After `init` + `install` + `sync`:
 │   │   └── .archive/        # sessions archived from the UI
 │   └── codegraph/           # `invariant scan` output
 ├── .agents/                 # canonical store — the only physical copy
-│   ├── skills/<name>/SKILL.md
-│   ├── agents/<name>.md
-│   ├── commands/<name>.md
-│   └── rules/<name>.md
+│   ├── skills/<pkg>-<name>/SKILL.md
+│   ├── agents/<pkg>-<name>.md
+│   ├── commands/<pkg>-<name>.md
+│   └── rules/<pkg>-<name>.md
 ├── CLAUDE.md                # generated by `invariant sync`
 └── .claude/                 # symlinks into .agents/
-    ├── agents/<name>.md  ->  ../../.agents/agents/<name>.md
-    ├── skills/<name>     ->  ../../.agents/skills/<name>
-    ├── commands/<name>.md
-    └── rules/<name>.md
+    ├── agents/<pkg>-<name>.md  ->  ../../.agents/agents/<pkg>-<name>.md
+    ├── skills/<pkg>-<name>     ->  ../../.agents/skills/<pkg>-<name>
+    ├── commands/<pkg>-<name>.md
+    └── rules/<pkg>-<name>.md
+```
+
+### Item names carry their package
+
+An item is stored under `<package-slug>-<item>`: the `frontend` skill of package
+`docs` lands at `.agents/skills/docs-frontend`, linked as
+`.claude/skills/docs-frontend`. Two packages can therefore ship a `frontend`
+skill without one clobbering the other, and removing one never touches the
+other's files.
+
+The name is a pure function of the package and the item — never of install order
+— so a package author can write the installed path by hand in an instruction;
+invariant does not rewrite content. An item already named `docs-frontend` inside
+package `docs` stays exactly that.
+
+You keep addressing items by their own name:
+
+```bash
+invariant add skill:docs/frontend      # installs .agents/skills/docs-frontend
+invariant remove skill:docs/frontend
+invariant inspect docs --paths         # prints the installed names and paths
 ```
 
+Full rules, including how the package name itself is resolved for GitHub
+installs: [docs/package-naming.md](docs/package-naming.md).
+
 ### One copy, many views
 
 `.agents/` holds the single physical copy of every activated item. What each
@@ -743,8 +814,8 @@ target gets depends on how it reads skills:
 |---|---|---|
 | `claude` | symlink into `.agents/` | symlink into `.agents/` |
 | `codex` | reads `.agents/skills/` — nothing written | embedded in `AGENTS.md` |
-| `cursor` | reads `.agents/skills/` — nothing written | `.cursor/rules/<name>.mdc` |
-| `copilot` | reads `.agents/skills/` — nothing written | `.github/instructions/<name>.instructions.md` |
+| `cursor` | reads `.agents/skills/` — nothing written | `.cursor/rules/<pkg>-<name>.mdc` |
+| `copilot` | reads `.agents/skills/` — nothing written | `.github/instructions/<pkg>-<name>.instructions.md` |
 | `aider` | embedded in `CONVENTIONS.md` | embedded in `CONVENTIONS.md` |
 
 Two consequences worth knowing: