skilld-harness 3.0.0-beta.1 → 3.0.0-beta.3

package/dist/skills/skilld/SKILL.md

@@ -1,25 +1,74 @@
 ---
 name: skilld
-description: Search, view, install, upgrade, verify, and remove Skills with skilld CLI, including private repository access.
+description: Search, run, view, install, update, verify, and remove Skills with skilld CLI, including private repository access.
 ---
 
 # Use skilld CLI
 
-Use skilld CLI to search for and install Skills.
+Use skilld CLI to search for, run, and install Skills.
+
+Run a Skill first. Install a Skill only when the user asks to keep it.
 
 ## Search for a Skill
 
 Run a focused search:
 
 ```sh
-skilld search <query>
+skilld search <query> --json
 ```
 
-Read the result names and descriptions before choosing.
+Read `data.items` before choosing a Skill.
+Use each item's `selector` for a Skill run.
 Refine the query when several Skills cover different tasks.
 
+Always use `--json` when an Agent runs Skill search.
+Check the exit code before reading stdout.
+If search fails, read the tagged JSON error from stderr.
+Use `--plain` only when another command needs stable text.
+Never parse formatted terminal output.
+
+## Run a Skill
+
+Run the selector returned by search:
+
+```sh
+skilld run <selector> --json
+```
+
+The command prints SKILL.md and writes no Skill files.
+It retains no remote Skill files after the command exits.
+Read the printed SKILL.md, then follow it for the current task.
+Prefer `skilld run` for a one-off task.
+
+Read `data.files` for each supporting file's path, kind, and size.
+The initial load prints no supporting file content.
+Read one only when the instructions name it:
+
+```sh
+skilld run <selector> --revision <data.revision> --file <path> --json
+```
+
+Run the exact `data.files[].readArgv` array when possible.
+It contains the source, exact revision, file path, and `--json`.
+Repeat `--file` to read several files in one command.
+
+Check `data.files[].readable` before you ask for a file.
+A file with `readable: false` never prints.
+Its `kind` is `executable` or `binary`.
+Tell the user the Skill needs an install to use that file.
+
+Report which Skill you ran and that skilld wrote no Skill files.
+Read `data.sourceStatus`, `data.origin`, and `data.revision`.
+A `verified` status covers where the Skill came from.
+It does not cover what the instructions ask you to do.
+If the status is `unverified`, tell the user before you follow the Skill.
+
 ## Install a Skill
 
+Install a Skill when the user wants it in every session.
+Install a Skill when it must run its own script.
+Ask the user before you install. An install writes files they did not request.
+
 Install the selector returned by search into the detected Agent target:
 
 ```sh
@@ -57,11 +106,18 @@ Use `view` to show one Skill's path, source status, and Agent targets.
 ## Maintain installed Skills
 
 ```sh
-skilld upgrade <skill>
+skilld update <skill>
+skilld update --check --json
 skilld verify <skill>
 skilld remove <skill>
 ```
 
-Use `upgrade` to install a newer Artifact.
+Use `update --check --json` to inspect update relations without changing files.
+Read each `data.items[].relation._tag` before changing files.
+Use `update <skill>` only when the relation is `available`.
+Treat `current`, `pinned`, and `notTracked` as no action.
+If the relation is `behind` or `diverged`, ask before changing files.
+If the relation is `unavailable`, report `failure.code` and `failure.message`.
+Treat `unavailable` as unknown. Do not infer a newer commit.
 Use `verify` to check the installed bytes and source status.
 Use `remove` only when the request names the Skill to remove.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",
@@ -44,6 +44,23 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "dependencies": {
+    "@ai-sdk/harness": "^1.0.87",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider-utils": "^5.0.30",
+    "@antfu/eslint-config": "^9.3.0",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^26.3.0",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "eslint": "^10.9.1",
+    "obuild": "^0.4.38",
+    "publint": "^0.3.24",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.11"
+  },
   "scripts": {
     "build": "obuild && node scripts/copy-skilld-maintained-skills.mjs",
     "lint": "eslint .",
@@ -52,25 +69,6 @@
     "test": "vitest",
     "test:run": "vitest run",
     "publint": "publint",
-    "attw": "node scripts/check-package-types.mjs",
-    "prepack": "pnpm run build"
-  },
-  "dependencies": {
-    "@ai-sdk/harness": "catalog:",
-    "ws": "catalog:",
-    "yaml": "catalog:",
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@ai-sdk/provider-utils": "catalog:",
-    "@antfu/eslint-config": "catalog:dev-lint",
-    "@arethetypeswrong/cli": "catalog:",
-    "@types/node": "catalog:dev-build",
-    "@typescript/native": "catalog:",
-    "eslint": "catalog:dev-lint",
-    "obuild": "catalog:dev-build",
-    "publint": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:dev-test"
+    "attw": "node scripts/check-package-types.mjs"
   }
-}
+}