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

package/dist/index.d.mts

@@ -117,6 +117,6 @@ interface CreateSkillHarnessOptions {
   /** HTTP adapter for npm metadata and immutable source archives. */
   readonly fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 }
-declare function createSkillHarness(options: CreateSkillHarnessOptions): SkillHarness;
-export { type CreateSkillHarnessOptions, type GeneratedSkill, type PackageSource, type SkillDestination, type SkillFile, type SkillHarness, type SkillOutputPolicy, type SkillReview, type SkillReviewFinding, type SkillRun, type SkillRunError, type SkillRunOptions, type SkillRunResult, type SourceAttempt, createSkillHarness };
+export declare function createSkillHarness(options: CreateSkillHarnessOptions): SkillHarness;
+export type { CreateSkillHarnessOptions, GeneratedSkill, PackageSource, SkillDestination, SkillFile, SkillHarness, SkillOutputPolicy, SkillReview, SkillReviewFinding, SkillRun, SkillRunError, SkillRunOptions, SkillRunResult, SourceAttempt };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/harness.ts"],"mappings":";;UAGiB;WACN;WACA;;KAGC;WAEC;WACA;;WAGA;WACA;WACA;;KAGD;WAEC;WACA,QAAQ;WACR,aAAa;;WAGb;WACA;WACA,aAAa;;WAGb;WACA;;UAGI;WACN;WACA;WACA;WACA;WACA;WACA;;UAGM;WACN,SAAS;;UAGH;WACN;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,OAAO,cAAc;WACrB,gBAAgB,cAAc;;WAE9B,UAAU;;UAGJ;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA,UAAU,cAAc;;KAGvB;WACK;WAA+B;;WAEjC;WACA;WACA,UAAU,cAAc;WACxB;;WAEE;WAA8B;WAA0B;;WACxD;WAA+B;WAA0B,QAAQ;;WACjE;WAAmC;WAA0B;;WAC7D;WAA6B;WAA0B;;WACvD;WAAkC;WAA0B;WAAuB;;WACnF;WAA4B;;KAEjC;WACK;WAAqB,OAAO,iBAAiB;;WAC7C;WAAsB,OAAO;;UAE7B;WACN,MAAM,OAAO,UAAU,UAAU,oBAAoB,QAAQ;;UAGvD;WACN,SAAS;;WAET,SAAS;;WAET,gBAAgB;WAChB,eAAe,QAAQ;;WAEvB,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ;;iBCkElE,mBAAmB,SAAS,4BAA4B"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/harness.ts"],"mappings":";;UAGiB;WACN;WACA;;KAGC;WAEC;WACA;;WAGA;WACA;WACA;;KAGD;WAEC;WACA,QAAQ;WACR,aAAa;;WAGb;WACA;WACA,aAAa;;WAGb;WACA;;UAGI;WACN;WACA;WACA;WACA;WACA;WACA;;UAGM;WACN,SAAS;;UAGH;WACN;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,OAAO,cAAc;WACrB,gBAAgB,cAAc;;WAE9B,UAAU;;UAGJ;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA,UAAU,cAAc;;KAGvB;WACK;WAA+B;;WAEjC;WACA;WACA,UAAU,cAAc;WACxB;;WAEE;WAA8B;WAA0B;;WACxD;WAA+B;WAA0B,QAAQ;;WACjE;WAAmC;WAA0B;;WAC7D;WAA6B;WAA0B;;WACvD;WAAkC;WAA0B;WAAuB;;WACnF;WAA4B;;KAEjC;WACK;WAAqB,OAAO,iBAAiB;;WAC7C;WAAsB,OAAO;;UAE7B;WACN,MAAM,OAAO,UAAU,UAAU,oBAAoB,QAAQ;;UAGvD;WACN,SAAS;;WAET,SAAS;;WAET,gBAAgB;WAChB,eAAe,QAAQ;;WAEvB,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ;;wBCkElE,mBAAmB,SAAS,4BAA4B"}

package/dist/skills/generate-package-skill/SKILL.md

@@ -6,6 +6,7 @@ description: Generate or update an Agent Skill for an npm or local package using
 # Generate a package Skill
 
 Create a focused Skill that helps an Agent use one package correctly.
+This Skill is for maintainers who author a draft Skill they own.
 
 ## Inputs
 

package/dist/skills/generate-project-skill/SKILL.md

@@ -6,6 +6,7 @@ description: Generate or update an Agent Skill from the observed workflows, boun
 # Generate a project Skill
 
 Create a compact, searchable Skill from the project itself.
+This Skill is for maintainers who author a draft Skill they own.
 
 ## Inputs
 

package/dist/skills/skilld/SKILL.md

@@ -1,14 +1,29 @@
 ---
 name: skilld
-description: Search, run, view, install, update, verify, and remove Skills with skilld CLI, including private repository access.
+description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs.
 ---
 
 # Use skilld CLI
 
-Use skilld CLI to search for, run, and install Skills.
+Use skilld CLI to find, load, install, inspect, restore, update, verify, and remove Skills.
 
 Run a Skill first. Install a Skill only when the user asks to keep it.
 
+## Use Agent output
+
+Use `--json` with `search`, `run`, and `update --check`.
+These are the only commands that support JSON output.
+Use `--plain` when another command needs stable text.
+
+Check the exit code before reading stdout.
+Read JSON success data only when `_tag` is `Success`.
+Read JSON failures from stderr.
+Report the error `code` and `message`.
+
+An update check can exit with code 1 and return valid JSON.
+Read its update relations before treating that exit as a failure.
+Never parse formatted terminal output.
+
 ## Search for a Skill
 
 Run a focused search:
@@ -21,11 +36,8 @@ 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.
+Do not guess a selector from the Skill name.
+Do not install a search result before reading its description.
 
 ## Run a Skill
 
@@ -63,6 +75,45 @@ 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.
 
+## List the Skills a Repository, curator, or collection names
+
+skilld.dev prints refs that name several Skills:
+
+- `gh:OWNER/REPOSITORY` names every Skill in one Repository.
+- `@LOGIN` names every Skill in one curator's collections.
+- `@LOGIN/SLUG` names every Skill in one collection.
+
+Run one of these refs to list its Skills:
+
+```sh
+skilld run @LOGIN/SLUG --json
+```
+
+The command prints an index and loads no Skill.
+Read `data.items` for each Skill's `name`, `owner`, `repository`, `description`, and `selector`.
+Run the `data.items[].runArgv` array to load one Skill.
+Pick the Skills the current task needs. Do not run every Skill in the index.
+
+## Choose the source
+
+Prefer the exact `skilld:` selector returned by Skill search.
+Hosted selectors use immutable artifact delivery from an exact Git commit.
+
+Use a local path only for a Skill the user already controls:
+
+```sh
+skilld run ./skills/my-skill --json
+skilld install ./skills/my-skill
+```
+
+Use `--direct` only for an explicit public GitHub selector.
+Direct mode bypasses artifact delivery and gives the `unverified` source status.
+It cannot access a private repository.
+Never add `--direct` merely to bypass a delivery failure.
+
+Private repository delivery requires a skilld.dev account and GitHub App access.
+If private access fails, check authentication before changing the selector.
+
 ## Install a Skill
 
 Install a Skill when the user wants it in every session.
@@ -75,41 +126,83 @@ Install the selector returned by search into the detected Agent target:
 skilld install <selector>
 ```
 
+The default scope is the current project.
+Project installs update `.skills/skilld-lock.yaml` and selected Agent targets.
+
 Install into global Agent targets:
 
 ```sh
 skilld install <selector> --global
 ```
 
+Use `--agent <agent>` when the user names an Agent target.
+Repeat `--agent` when the user names several Agent targets.
+Do not guess a target when detection and `agent.targets` are empty.
+
+Use `--mode copy` or `--mode symlink` only when the user chooses a mode.
+Otherwise, use the configured `install.mode`.
+
 Install this skilld-maintained Skill globally:
 
 ```sh
 skilld install skilld --global
 ```
 
+Install every Skill a Repository, curator, or collection names:
+
+```sh
+skilld add gh:OWNER/REPOSITORY
+skilld add @LOGIN/SLUG --global
+```
+
+`skilld add` accepts `--global`, `--agent`, and `--mode` like `skilld install`.
+It prints one `Installed Skill` line per Skill.
+Run `skilld run` with the same ref first, then confirm the list with the user.
+`skilld add` with one Skill selector installs that Skill like `skilld install`.
+
 Always use the source selector shown by `skilld search`.
-If private repository access is required, run `skilld auth login`.
-Do not print access tokens or copy them into project files.
+After installation, report the Skill name, scope, Agent targets, and source status.
+
+## Restore locked Skills
+
+Restore the current project from its lockfile:
+
+```sh
+skilld install
+```
 
-After installation, report the installed Skill name and Agent target.
+Restore global Skills from the global scope:
 
-## View a Skill
+```sh
+skilld install --global
+```
+
+A verified remote Skill restores its exact locked commit through artifact delivery.
+An unverified remote Skill requires the recovery command shown by skilld.
+Do not convert a verified source to direct mode during recovery.
+
+Never delete a lockfile or Agent target to repair an install.
+Preserve the files and report the exact failure first.
+
+## Inspect installed Skills
 
 ```sh
 skilld list
+skilld list --global
 skilld view <skill>
+skilld view <skill> --global
 ```
 
-Use `list` to show installed Skills.
-Use `view` to show one Skill's path, source status, and Agent targets.
+Use `list` to find installed names in one scope.
+Use `view` to inspect a Skill before any mutation.
+Read its path, source, source status, and Agent targets.
 
-## Maintain installed Skills
+## Check and apply updates
 
 ```sh
-skilld update <skill>
 skilld update --check --json
-skilld verify <skill>
-skilld remove <skill>
+skilld update <skill>
+skilld update <skill> --global
 ```
 
 Use `update --check --json` to inspect update relations without changing files.
@@ -119,5 +212,110 @@ 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.
+
+Update one named Skill unless the user explicitly requests all updates.
+Use `--global` only for a Skill in the global scope.
+Leave `--interactive` to a human terminal session.
+
+## Verify source integrity
+
+```sh
+skilld verify <skill>
+```
+
+Use `verify` to check installed bytes against recorded source data.
+A successful check confirms provenance and integrity only.
+It does not approve the Skill instructions.
+
+If verification fails, do not hand edit a managed Skill.
+Use `view` to inspect its source before update or restore.
+
+## Report outdated and unmanaged Skills
+
+Check the current scope:
+
+```sh
+skilld outdated --plain
+```
+
+Check both scopes and every Agent target directory:
+
+```sh
+skilld outdated --all --plain
+```
+
+Use `outdated` for stale, unverified, local, and unmanaged Skill reports.
+Read every proposed command before using it.
+Never delete an unmanaged Skill unless the user names it for removal.
+
+## Manage account authentication
+
+Check account authentication before starting login:
+
+```sh
+skilld auth status --plain
+```
+
+Start login only when private artifact delivery requires it:
+
+```sh
+skilld auth login --plain
+```
+
+Private repository access also requires the skilld GitHub App installation.
+Credentials stay in the operating system keychain.
+Never print access tokens or copy them into files.
+
+Log out only when the user explicitly asks:
+
+```sh
+skilld auth logout --plain
+```
+
+## Manage configuration
+
+Read account level configuration before changing it:
+
+```sh
+skilld config list --plain
+skilld config get agent.targets --plain
+skilld config get install.mode --plain
+```
+
+Only `agent.targets` and `install.mode` are supported keys.
+Set a key only when the user explicitly requests a persistent default.
+
+```sh
+skilld config set agent.targets codex,claude-code --plain
+skilld config set install.mode copy --plain
+```
+
+Valid install modes are `copy` and `symlink`.
+Configuration changes affect later commands across projects.
+
+## Remove a Skill
+
+Inspect the named Skill and its scope before removal:
+
+```sh
+skilld view <skill> --plain
+skilld remove <skill> --plain
+```
+
+Add `--global` to both commands for a global Skill.
+Remove only the Skill and scope the user names.
+Report the removed Agent targets and whether recovery needs a reinstall.
+
+## Handle failures
+
+Preserve the original error code and message.
+Do not hide a failure with a fallback source or scope.
+Do not retry with `--direct` because it changes the source status.
+
+For authentication errors, run `skilld auth status` before login.
+For target errors, inspect `agent.targets` and the requested `--agent` values.
+For lockfile errors, preserve the lockfile and report its path.
+For target conflicts, stop before overwriting existing files.
+
+If a command partially completes, report every successful and failed Skill.
+Never claim success from generated commands that were not run.

package/dist/skills.d.mts

@@ -1,8 +1,8 @@
 import { HarnessV1Skill } from "@ai-sdk/harness";
-declare function harnessSkillNames(): Promise<ReadonlyArray<string>>;
-declare function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>>;
-declare function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill>;
-declare const DEFAULT_OUTPUT_POLICY: Readonly<{
+export declare function harnessSkillNames(): Promise<ReadonlyArray<string>>;
+export declare function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>>;
+export declare function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill>;
+export declare const DEFAULT_OUTPUT_POLICY: Readonly<{
   maxSourceFiles: 2000;
   maxSourceFileBytes: number;
   maxSourceBytes: number;
@@ -10,5 +10,4 @@ declare const DEFAULT_OUTPUT_POLICY: Readonly<{
   maxOutputFileBytes: number;
   maxOutputBytes: number;
 }>;
-export { DEFAULT_OUTPUT_POLICY, harnessSkillNames, loadSkilldMaintainedSkill, skilldMaintainedSkillNames };
 //# sourceMappingURL=skills.d.mts.map

package/dist/skills.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";iBAsDsB,qBAAqB,QAAQ;iBAK7B,8BAA8B,QAAQ;iBAKtC,0BAA0B,eAAe,QAAQ;cAqB1D,uBAAqB"}
+{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";wBAsDsB,qBAAqB,QAAQ;wBAK7B,8BAA8B,QAAQ;wBAKtC,0BAA0B,eAAe,QAAQ;qBAqB1D,uBAAqB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.5",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",
@@ -45,18 +45,18 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@ai-sdk/harness": "^1.0.87",
+    "@ai-sdk/harness": "^1.0.100",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@ai-sdk/provider-utils": "^5.0.30",
-    "@antfu/eslint-config": "^9.3.0",
+    "@ai-sdk/provider-utils": "^5.0.36",
+    "@antfu/eslint-config": "^9.5.1",
     "@arethetypeswrong/cli": "^0.18.5",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.4.1",
     "@typescript/native": "npm:typescript@7.0.2",
     "eslint": "^10.9.1",
-    "obuild": "^0.4.38",
+    "obuild": "^0.4.39",
     "publint": "^0.3.24",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.11"