skillcask 0.4.1 → 0.6.0

package/README.md

@@ -77,7 +77,6 @@ skills.lock                  # lock, commit it
 .agents/skills/<name>/       # installed skill (gitignored)
 .agents/skills/.skillcask-installed  # what this machine installed (gitignored)
 .claude/skills/<name>  -> ../../.agents/skills/<name>
-.junie/skills/<name>   -> ../../.agents/skills/<name>
 .gitignore                   # managed block
 ```
 
@@ -108,7 +107,7 @@ github = { type = "github", url = "https://api.github.com" }   # GitHub Enterpri
 "anthropics/skills" = { github = true, skills = ["pdf"] }      # default branch
 
 [agents]
-targets = [".claude/skills", ".junie/skills"]
+targets = ["claude", "kiro"]   # agent names or paths with a "/"; default: config.toml, else ["claude"]
 local = ".skills"        # project skills
 
 [policy]
@@ -119,6 +118,32 @@ github-requires = false  # true: dependencies may come from GitHub
 allow-sources = ["acme", "own", "packagist", "github"]   # only these sources; default: all
 ```
 
+### Agents
+
+Most agents read `.agents/skills` themselves (Codex, Copilot, Cursor, Gemini CLI, OpenCode, Amp,
+Junie, Devin/Windsurf, Roo Code, Cline, Goose, Factory, Mistral Vibe), so they need no link.
+`[agents] targets` lists the agents that need one, by name, or any directory as a path with a `/`:
+
+| Name | Project | Home (`--global`) |
+|---|---|---|
+| `claude` | `.claude/skills` | `~/.claude/skills` |
+| `kiro` | `.kiro/skills` | `~/.kiro/skills` |
+| `junie` | store | `~/.junie/skills` |
+| `codex`, `copilot`, `cursor`, `gemini`, `opencode`, `amp`, `devin`, `roo`, `cline`, `goose`, `factory`, `vibe` | store | store |
+
+Set the list once in `config.toml` next to the global manifest; a `skills.toml` that sets
+`targets` replaces it. Manifests from before 0.6.0 carry an explicit list: delete the line to
+follow `config.toml`.
+
+```toml
+# ~/.config/skillcask/config.toml
+[agents]
+targets = ["claude", "kiro"]
+```
+
+When a target is dropped, the next `install` removes the links skillcask made there; `doctor`
+reports them. `status` prints the targets, where they came from and the directories they link.
+
 Constraints follow Composer semantics: `^0.3` means `>=0.3.0 <0.4.0`, `~1.2` means
 `>=1.2 <2.0`, and pre-releases are only selected when the constraint names a stability
 (`^1.0@beta`).
@@ -148,6 +173,18 @@ allow-sources = ["https://gitlab.example.com/", "github"]
 enforce = ["allow-sources"]
 ```
 
+An enforced `min-release-age` also applies to a repository's own `min-release-age`: a project
+may only make it longer. Exceptions, by URL prefix, stay in `config.toml`:
+
+```toml
+[policy]
+min-release-age = "3d"
+enforce = ["min-release-age"]
+
+[policy.repository-min-release-age]
+"https://gitlab.example.com/" = "0"   # internal skills, reviewed in merge requests
+```
+
 `config.toml` and the environment take URL prefixes, not repository names, since a name means
 whatever a project calls it. `skillcask status` prints each key that is set and where it came
 from.
@@ -199,8 +236,8 @@ skillcask -g install --frozen    # e.g. from a dotfiles repository
 
 - `skills.toml`, `skills.lock` and an optional `auth.json` live in `~/.config/skillcask`
   (`$XDG_CONFIG_HOME/skillcask`; `SKILLCASK_HOME` overrides both). Keep them in your dotfiles.
-- Skills go to `~/.agents/skills` (read by Codex), with links in `~/.claude/skills` and
-  `~/.junie/skills` (`[agents] targets`, relative to home). Links are absolute, so a symlinked
+- Skills go to `~/.agents/skills` (read by most agents), with links in `~/.claude/skills`
+  (`[agents] targets`, see Agents). Links are absolute, so a symlinked
   `~/.claude` works. `[agents] local` does not apply.
 - Personal skills you wrote by hand stay where they are and are not linked anywhere.
 - The list of managed paths is `~/.agents/skills/.skillcask-installed`, local to the machine;
@@ -208,7 +245,7 @@ skillcask -g install --frozen    # e.g. from a dotfiles repository
 
 ### Commands
 
-Every command except `publish` takes `-g, --global`.
+Every command except `publish` and `validate` takes `-g, --global`.
 
 | Command | |
 |---|---|
@@ -217,13 +254,16 @@ Every command except `publish` takes `-g, --global`.
 | `add github:<owner/repo>[/skill][@version-or-ref]` | The same from a GitHub repository, see below. |
 | `remove <vendor/name>…` | Drop from manifest and lock; delete files, links and gitignore lines. |
 | `install [--frozen]` | Install the lock. `--frozen` (implied by `CI`) fails when the lock is out of date. |
-| `update [vendor/name…]` | Re-resolve within constraints. |
-| `outdated` | Newer versions, and when cooled-down ones become eligible. |
+| `update [vendor/name…] [--diff]` | Re-resolve within constraints. `--diff` prints what changes in each updated or added package; it does not ask before installing. |
+| `outdated [--strict]` | Newer versions, and when cooled-down ones become eligible. `--strict` exits 1 when `update` would lock a newer version. |
+| `diff [vendor/name] [--to constraint]` | Unified diff of skill files from the locked version to the one `update` would lock, see below. |
+| `info <vendor/name[@constraint]\|github:owner/repo\|skill>` | A package's skills, versions, description, license and requirements, or which package installs a skill. |
 | `status` | Exit 1 when manifest, lock or installed files disagree. |
-| `doctor [--fix]` | Broken or committed links, stale gitignore block, modified skills. |
+| `doctor [--fix]` | Broken or committed links, stale gitignore block, modified skills; lists each check it ran. |
 | `search <query>` | Packagist (`type=ai-agent-skill`) and skill packages of the other repositories, GitLab included. |
 | `auth set\|remove <host>` | Keep a registry token in git's credential helper (Keychain, Credential Manager, libsecret). |
 | `publish --vendor v --base-url URL --out DIR [--inline] [--dist-url TPL] [paths…]` | Build a static Composer repository from a monorepo. |
+| `validate [paths…]` | Check `SKILL.md` files against the Agent Skills spec, see below. |
 | `<other>` | Runs `skillcask-<other>` from `PATH`, like git and cargo plugins. |
 
 Exit codes: 0 ok, 1 manifest/lock/status problems, 2 authentication, 3 network, 4 hash mismatch,
@@ -234,6 +274,37 @@ the next step on a `hint:` line. For coding agents, `--agent` or `SKILLCASK_AGEN
 uncoloured, tab-separated output with only the rows that need action; it is on by itself when
 `AI_AGENT` or `CLAUDECODE=1` is set, unless `SKILLCASK_AGENT=0`.
 
+A failed connection, HTTP 429 or a 5xx response is retried twice, after 1 s and 2 s or after the
+`Retry-After` seconds the server sends. A `Retry-After` above 60 s, a spent GitHub rate limit, a
+timeout or a TLS error fails at once.
+
+`add`, `update` and `outdated` warn about a package its registry marks `abandoned` and name the
+replacement when there is one (and it is a valid package name). Installing from the lock does not ask the registry.
+
+**Reviewing an update:** a skill is a prompt, so read what changes before you take it.
+`skillcask diff` prints a unified diff of the skill files, from the locked version to the one
+`update` would lock (newest within the constraint, past the cooldown), for every entry in
+`skills.toml` with a newer version; `diff vendor/name --to 2.0.0` compares one package with
+another version. A package new to the lock, such as a dependency a new version adds, is shown as
+all added. Nothing is installed or written. Control characters, bidi controls and other
+invisible characters in the diff are shown as `<U+XXXX>` (a carriage return too, when the line
+ends change), and invisible characters in changed files are warned about. Files over 1 MiB or
+10,000 lines print `Files differ (too large to show)`. `update --diff` prints the same diff
+before it writes the lock, then installs without asking: run `skillcask diff` first to review
+and decide. A scheduled CI job can run `skillcask outdated --strict` (exit 1 when something is to
+update), then `skillcask update --diff` and open a pull request with the output.
+
+**Where a skill comes from:** `skillcask info vendor/name` shows the package's skills with their
+descriptions, its versions, description, license, `abandoned` and `requires`, for the locked
+version or else the newest one `add` would take (`@constraint` for another); `info
+github:owner/repo` lists the skills of a GitHub repository before you add it. `skillcask info
+<skill>` names the package that installs an installed skill and the `skills.toml` entry, or the
+chain of `requires`, that brings it in.
+
+**Merge conflicts in `skills.lock`:** a lock with conflict markers fails with a hint. Resolve
+`skills.toml`, keep either side of the lock (`git checkout --theirs skills.lock`) and run
+`skillcask install`: it locks the entries from the other side that the kept lock lacks.
+
 ### Skills from GitHub and skills.sh
 
 [skills.sh](https://skills.sh) lists skills as `owner/repo/skill`, for example
@@ -291,6 +362,13 @@ what you picked.
   and paths that collide by case or Unicode form fail a skill that contains them, and are
   skipped outside the selected skills.
 - No package code runs, ever. No telemetry.
+- `add` and `update` (and `install` when it resolves) warn about characters a reviewer cannot
+  see in the text files of new content: bidi controls (`U+202A`-`U+202E`, `U+2066`-`U+2069`,
+  `U+200E`, `U+200F`, `U+061C`), zero-width characters (`U+200B`-`U+200D`, `U+2060`, `U+FEFF`) and
+  Unicode tags (`U+E0000`-`U+E007F`), as `warning: acme/x: skills/foo/SKILL.md:12: U+202E
+  RIGHT-TO-LEFT OVERRIDE`, at most five per file. A leading byte order mark and a zero width
+  joiner inside an emoji are not reported; right-to-left and Indic text can trigger warnings.
+  Installing from the lock does not warn again.
 - `min-release-age` for GitHub sources uses times GitHub sets: release publication for tags,
   push times from the Activity API for branches. A tag without a release, or a ref GitHub lists no
   pushes for, falls back to commit dates, which the committer sets; reviewing what `add`/`update`
@@ -319,6 +397,22 @@ This writes `packages.json`, `p2/acme/<name>.json` and deterministic zips under
 versions are immutable, and re-running on unchanged skills changes no file. Serve the directory
 over HTTPS.
 
+Check the skills before publishing; `validate` exits 1 on any error and warns about invisible
+Unicode, as `add` does:
+
+```sh
+skillcask validate skills/
+```
+
+It follows the [Agent Skills specification](https://agentskills.io/specification): `name` 1-64
+lowercase letters, digits and single hyphens, equal to the directory name; `description` 1-1024
+characters; `compatibility` at most 500. Without paths it searches the current directory.
+`publish` skips a `SKILL.md` without `name` or `version` and names it in a warning.
+
+To retire a skill, publish a new version with `deprecated: true`, or `deprecated: vendor/name`
+naming its replacement, in the frontmatter. It becomes Composer's `abandoned`, and consumers see a
+warning on `add`, `update` and `outdated`.
+
 Hosts that cannot serve `/` inside file names (GitLab's Generic Package Registry) take a single
 file instead:
 

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "skillcask",
-      "version": "0.4.1"
+      "version": "0.6.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.4.1"
+  "version": "0.6.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/puniserv/skillcask/releases/download/v0.4.1"
+    "https://github.com/puniserv/skillcask/releases/download/v0.6.0"
   ],
   "bin": {
     "skillcask": "run-skillcask.js"
@@ -104,7 +104,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.4.1",
+  "version": "0.6.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"