skillcask 0.5.0 → 0.7.0

package/README.md

@@ -60,6 +60,27 @@ build provenance attestations:
 gh attestation verify skillcask-x86_64-unknown-linux-gnu.tar.xz -R puniserv/skillcask
 ```
 
+**GitHub Actions**
+
+```yaml
+permissions:
+  contents: read
+  attestations: read   # for the provenance check
+steps:
+  - uses: actions/checkout@<sha>
+  - uses: puniserv/skillcask@<commit sha of a release tag>   # vX.Y.Z
+    with:
+      version: X.Y.Z               # needed when the action is pinned to a sha, not a tag
+      args: install --frozen       # default
+      # working-directory: .
+      # verify-attestation: "true" # default
+```
+
+The action downloads the release archive for the runner (Linux x64 and arm64, macOS, Windows
+x64), checks its sha256 and its build provenance attestation, puts `skillcask` on `PATH` and runs
+it with `args`. It runs no other action. Used at a tag (`@vX.Y.Z`) it takes the version from the
+tag.
+
 ## Use
 
 ```sh
@@ -77,7 +98,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 +128,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]
@@ -117,8 +137,35 @@ allow-ranges = true      # false: every version must be exact
 packagist = true         # false: drop the implicit Packagist repository
 github-requires = false  # true: dependencies may come from GitHub
 allow-sources = ["acme", "own", "packagist", "github"]   # only these sources; default: all
+deny-patterns = false    # true: risky patterns in new skill text fail instead of warning
 ```
 
+### 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`).
@@ -135,8 +182,8 @@ Policy can also come from `config.toml` next to the global manifest (`~/.config/
 from the environment. The first layer that sets a key wins:
 
 1. `SKILLCASK_ALLOW_SOURCES`, `SKILLCASK_MIN_RELEASE_AGE`, `SKILLCASK_ALLOW_RANGES`,
-   `SKILLCASK_PACKAGIST`, `SKILLCASK_GITHUB_REQUIRES` (overriding an enforced key prints a
-   warning);
+   `SKILLCASK_PACKAGIST`, `SKILLCASK_GITHUB_REQUIRES`, `SKILLCASK_DENY_PATTERNS` (overriding an
+   enforced key prints a warning);
 2. keys `config.toml` lists in `enforce`: a project that sets them otherwise fails;
 3. `[policy]` in `skills.toml`;
 4. the other keys of `config.toml`, as defaults.
@@ -148,6 +195,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 +258,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;
@@ -215,6 +274,7 @@ Every command except `publish` and `validate` takes `-g, --global`.
 | `init` | Create `skills.toml`. |
 | `add <vendor/name>[@constraint] [--repository r]` | Resolve, lock and install. |
 | `add github:<owner/repo>[/skill][@version-or-ref]` | The same from a GitHub repository, see below. |
+| `add git:<https-url>[@version-or-ref]` | The same from any git repository over HTTPS, 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…] [--diff]` | Re-resolve within constraints. `--diff` prints what changes in each updated or added package; it does not ask before installing. |
@@ -229,6 +289,11 @@ Every command except `publish` and `validate` takes `-g, --global`.
 | `validate [paths…]` | Check `SKILL.md` files against the Agent Skills spec, see below. |
 | `<other>` | Runs `skillcask-<other>` from `PATH`, like git and cargo plugins. |
 
+`status`, `outdated`, `info`, `search` and `doctor` take `--json`: one JSON document on one line of
+stdout, with the same exit code; warnings and errors stay on stderr. Package text in it is
+escaped as in the terminal (`<U+202E>`). For example `skillcask outdated --json | jq
+'.packages[] | select(.within != .locked)'`.
+
 Exit codes: 0 ok, 1 manifest/lock/status problems, 2 authentication, 3 network, 4 hash mismatch,
 5 IO or archive error.
 
@@ -308,8 +373,29 @@ entry; `install` from the lock uses none, it downloads the pinned archive. Set `
 for a higher limit and for private repositories. `SKILLCASK_GITHUB_API` points at GitHub
 Enterprise (`https://ghe.example.com/api/v3`).
 
-skills.sh itself is not queried: its API needs a Vercel token. Search on the website, then add
-what you picked.
+skills.sh itself is not queried: its API is undocumented and may change without notice. Search
+on the website, then add what you picked.
+
+### Skills from any git repository
+
+GitLab, Bitbucket, Azure DevOps, Gitea or a self-hosted server work without a Composer registry:
+
+```sh
+skillcask add git:https://gitlab.example.com/acme/skills.git
+skillcask add git:https://gitlab.example.com/acme/skills.git@main
+```
+
+```toml
+"acme/skills" = { git = "https://gitlab.example.com/acme/skills.git", version = "^1.0" }
+```
+
+Versions, `ref` and `skills = [...]` work as for GitHub; the entry is named after the last two
+parts of the URL. skillcask speaks git's HTTPS protocol itself: no git binary runs, so no hook or
+filter of the repository can. It fetches the one commit it needs and checks every file against
+the commit's object ids. Credentials come from the same places as for registries (`auth.json`,
+the credential helper, `$CI_JOB_TOKEN` in GitLab CI). Git servers keep no release or push times,
+so `min-release-age` uses commit dates, which the committer sets; a branch whose newest commit is
+too young falls back to an older commit when the server supports partial fetches (`filter`).
 
 ## Security
 
@@ -332,6 +418,22 @@ what you picked.
   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.
+- The same commands warn about lines that usually mean harm, as `warning: acme/x:
+  skills/foo/SKILL.md:12: downloads code into a shell`, at most five per file:
+
+  | Warning | Matches (case-insensitive) |
+  |---|---|
+  | downloads code into a shell | `curl`, `wget`, `irm`, `iwr`, `Invoke-WebRequest` or `Invoke-RestMethod` piped (`\|`) into `sh`, `bash`, `zsh`, `dash`, `iex`, `Invoke-Expression`, `python`, `perl`, `ruby` or `node`, also after `sudo` |
+  | decodes base64 and runs it | `base64 -d`, `base64 --decode`, `b64decode` or `FromBase64String` with a pipe into a shell, `eval`, `exec(` or `iex` |
+  | reads SSH keys | `~/.ssh`, `$HOME/.ssh`, `id_rsa`, `id_ed25519` |
+  | reads system account files | `/etc/passwd`, `/etc/shadow` |
+  | tells the agent to ignore its instructions | "ignore (all) previous/prior instructions", "disregard all previous/prior" |
+
+  Skills that teach shell setup trigger some of these legitimately, so they are warnings. With
+  `deny-patterns = true` under `[policy]` (or enforced in `config.toml`) they fail the command
+  with exit 1 and nothing is written.
+- Plain git sources pin the commit; the lock's `dist-sha256` hashes the commit's file list
+  (path, mode, sha256 of the content), so it does not depend on how a server packs objects.
 - `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`

package/npm-shrinkwrap.json

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

package/package.json

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