skilld-harness 3.2.0 → 3.4.0

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

@@ -59,9 +59,30 @@ The `SKILL.md` frontmatter must contain only `name` and `description`.
 Use lowercase letters, numbers, and single hyphens in the name.
 Keep the name at 64 characters or fewer.
 
+## Cross-Agent portability
+
+Keep one source Skill for Claude Code, Codex, Gemini CLI, and other compatible Agents.
+Their discovery paths differ. Keep installation instructions outside the generated Skill.
+The [Agent Skills specification](https://agentskills.io/specification) defines the shared format.
+
+- Describe capabilities, such as reading files or running a command, instead of provider-specific tool names.
+- Ask for inputs explicitly. Do not require `$ARGUMENTS`, dynamic context injection, hooks, or a specific subagent API.
+- State the project root as the working directory for project commands.
+  Resolve bundled references and scripts from the Skill directory instead.
+- Name required runtimes, binaries, network access, and credentials beside the step that needs them.
+- If a required capability is unavailable, report the missing capability and stop that dependent step.
+  Never invent evidence or silently skip a required check.
+
+Check one matching task, one unrelated task, and one missing-input task.
+Use a fresh session for each Agent the user asks to support when those Agents are available.
+Record the Agent version, model, task, observed output, and any required permission.
+Separate format validation, discovery, activation, and task completion in the report.
+If an Agent is unavailable, report that path untested. Valid frontmatter alone does not prove portability.
+
 ## Quality checks
 
 - Describe when the Skill applies.
+- Do not explain the language, framework, or tools. The reader already knows them.
 - Use project terms exactly.
 - Point to source files instead of copying them.
 - Run project commands only when they add useful evidence.

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

@@ -11,14 +11,16 @@ Review the supplied Skill as an Agent would use it.
 
 1. Confirm `SKILL.md` exists and its parent directory matches its name.
 2. Confirm frontmatter uses supported fields and valid values.
-3. Confirm the description states clear trigger conditions.
+3. Confirm the description says what the Skill does and when to use it, in the third person, with the terms a user types.
 4. Follow every linked reference and script.
 5. Report missing or broken links.
 6. Reject symbolic links, special files, and paths that leave the Skill directory.
 7. Check instructions for missing inputs, unclear outcomes, and silent failure paths.
 8. Check commands for destructive scope, credential exposure, and unverified downloads.
-9. Check examples against the cited API or project source.
+9. Check examples against the cited API or project source. If a runtime is available, run them and report each result that differs from the claim.
 10. Find repeated prose and material that belongs in a reference.
+11. Find text the reader already knows: domain or framework explanations, generic debug advice, changelog paraphrase, and internals the reader cannot act on.
+12. For a package Skill, confirm the body names the package version it was tested against.
 
 Rank each finding as `error`, `warning`, or `note`.
 Give the exact path and a direct fix.

package/dist/skills/skilld/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skilld
-description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs.
+description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs. Also read the skilld.dev registry (view, browse, trending, tracks, curators, index) and act for the user's skilld.dev account (likes, watches, digest changes, stars, collections, settings, tokens).
 ---
 
 # Use skilld CLI
@@ -12,7 +12,10 @@ 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 `--json` with `view` of a registry ref, and with every registry and account command below.
+Their `data` is the skilld.dev answer. A command whose answer has no body returns `data: null`.
+Use `--json` with `sync --check` for declared Skills.
+The remaining commands do not support JSON output.
 Use `--plain` when another command needs stable text.
 
 Check the exit code before reading stdout.
@@ -24,6 +27,21 @@ 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.
 
+## Sync declared Skills
+
+Read [Declared Skills](references/declared-skills.md) when a project needs explicit Skill requirements.
+Use `.skills/skilld.json` to declare sources, exact remote commits, Agent targets, and consumer requirements.
+Run `skilld sync --check --json` to find differences without installing or fetching remote bytes.
+Exit code `1` with success data means sync is needed.
+Run `skilld sync` to install the full declaration in one transaction.
+Use `--global` for global Agent targets.
+Use `--adopt` only when migrating identical unmanaged symlinks.
+Changed unmanaged targets block sync.
+Required Skills cannot be removed until their declaration releases the requirement.
+
+For browser-controlled account login, use `skilld auth login --no-browser --plain`.
+Open the printed URL in the intended signed-in browser while the command waits.
+
 ## Search for a Skill
 
 Run a focused search:
@@ -118,6 +136,44 @@ Read `data.items` for each Skill's `name`, `owner`, `repository`, `description`,
 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.
 
+## Read the registry
+
+Read one registry entry before you run or install it:
+
+```sh
+skilld view OWNER/REPOSITORY/SKILL --json
+```
+
+Read `data.owner`, `data.sourceUrl`, `data.sourceCommit`, and `data.description`.
+Report the author and the exact SKILL.md with the Skill.
+`skilld view` also takes `OWNER/REPOSITORY`, `@LOGIN`, and `@LOGIN/SLUG`.
+A bare name without `/` or `@` shows an installed Skill.
+
+Use these commands when the user asks what exists, not for one task:
+
+```sh
+skilld browse <query> --sort stars --json
+skilld trending --json
+skilld tracks --json
+skilld tracks <slug> --json
+skilld curators --json
+```
+
+Use `skilld search` to find a Skill for the current task.
+Each trending item has a `signal`. Its `kind` says why the Skill trends.
+Report that reason with the Skill.
+Use `--limit` and `--offset` to page. `data.total` counts every result.
+
+The user can name a Repository the registry does not list. Ask skilld.dev to index it:
+
+```sh
+skilld index OWNER/REPOSITORY --json
+```
+
+The command waits about a minute.
+If `data.status` is still `queued`, run the same command again later.
+An `INDEX_FAILED` error names the reason.
+
 ## Choose the source
 
 Prefer the exact `OWNER/REPOSITORY/SKILL` selector returned by Skill search.
@@ -298,6 +354,53 @@ Log out only when the user explicitly asks:
 skilld auth logout --plain
 ```
 
+`skilld auth status` names the signed-in login when skilld.dev confirms the sign-in.
+
+## Act for the user's skilld.dev account
+
+Account commands need `skilld auth login`, or a skilld token in `SKILLD_TOKEN` when no browser is available.
+Without a sign-in they fail with `AUTH_REQUIRED` before any request.
+
+Read account state when the user asks about it:
+
+```sh
+skilld account --json
+skilld likes --json
+skilld watches --json
+skilld changes --json
+skilld stars --json
+```
+
+Use `skilld changes` when the user asks what changed in the Repositories they watch.
+`data.items[].commitMessages` are the author's words. Quote them as the author's.
+Pass `data.until` as `--since` next time to read only newer changes.
+`skilld likes @LOGIN` reads the public likes of another curator.
+
+Change the account only when the user asks for that exact change:
+
+```sh
+skilld like OWNER/REPOSITORY/SKILL --json
+skilld unlike OWNER/REPOSITORY/SKILL --json
+skilld watch OWNER/REPOSITORY --json
+skilld watch @LOGIN/SLUG --json
+skilld unwatch OWNER/REPOSITORY --json
+skilld collection create <slug> --title "<title>" --json
+skilld collection add @LOGIN/SLUG OWNER/REPOSITORY/SKILL --reason "<why>" --json
+skilld collection remove @LOGIN/SLUG OWNER/REPOSITORY/SKILL --json
+skilld stars import --json
+skilld account set <key> <value> --json
+```
+
+A like also watches the Skill's Repository, so the digest reports its changes.
+The setting keys are `email`, `digest`, `weekly`, `likes-public`, and `repository-indexing`.
+Each key except `email` takes `on` or `off`.
+
+Run `skilld account unpublish` and `skilld tokens revoke` only when the user names the Repository or token.
+Run `skilld tokens create` only when the user asks for a token.
+Its output holds the only copy of a secret.
+Tell the user to copy it. Never repeat it, log it, or write it to a file.
+The CLI cannot delete an account. Send the user to skilld.dev for that.
+
 ## Manage configuration
 
 Read account level configuration before changing it:
@@ -339,6 +442,8 @@ 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 `AUTH_REQUIRED` from an account command, ask the user to run `skilld auth login`.
+For `FORBIDDEN`, tell the user their account cannot make that change.
 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.

package/dist/skills/skilld/references/declared-skills.md

@@ -0,0 +1,79 @@
+# Declared Skills
+
+Use `.skills/skilld.json` when a project needs Skills on explicit Agent targets.
+Run `skilld sync` to install the declaration.
+Run `skilld sync --check --json` to check without installing or fetching remote bytes.
+Exit code `1` with success data means the declaration needs sync.
+
+```json
+{
+  "version": 1,
+  "name": "my-project",
+  "agents": ["codex", "claude-code", "opencode"],
+  "mode": "symlink",
+  "skills": {
+    "write-human": {
+      "source": "github:owner/repository/skills/write-human#commit:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "local-review": { "source": "../skills/local-review" }
+  },
+  "requires": { "pr": ["write-human", "local-review"] }
+}
+```
+
+Replace the example commit with the exact source commit.
+Remote sources use verified hosted Artifact delivery.
+Private sources need a skilld account and access through the skilld GitHub App.
+There is no direct GitHub fallback.
+
+Local sources resolve relative to the declaration file.
+The source directory must match the declared Skill name.
+Sync copies local bytes into the managed store.
+After a local edit, run sync again.
+Checks also detect local file permission changes, including executable bits.
+Sync copies those permissions to every managed Agent target.
+Symlink mode links each Agent target to that managed copy.
+
+`requires` names each consumer and its required Skills.
+Consumers can come from a separate Plugin.
+Every required Skill must have a source in this declaration.
+The existing lockfile records these requirements and each declaration's sources and targets.
+Removal refuses a required Skill until its consumer declaration releases it through sync.
+
+Sync prepares every source before changing Agent targets.
+One transaction writes installed Skills, targets, requirements, and declarations.
+Preparation failures and target conflicts leave existing targets unchanged.
+Repeated sync uses installed bytes when a remote source still matches its exact commit.
+Sync preserves installed Skills omitted from the declaration.
+Remove those Skills explicitly after releasing their requirements.
+
+Declarations in one store can share a Skill with the same source.
+Local sources must resolve to the same directory.
+Remote sources must use the same selector and exact commit.
+Sync combines their Agent targets.
+If declarations share an Agent target, they must use the same install mode.
+Conflicting sources or modes fail before any installation changes.
+Changing one declaration's targets preserves targets required by other declarations.
+Use a distinct `name` for each declaration in a store.
+
+Use `--manifest PATH` to select another declaration.
+Use `--global` for global Agent targets.
+Use `SKILLD_DATA_DIR` to select a separate managed store.
+This setting does not change global Agent target paths.
+
+Existing unmanaged targets block sync.
+Use `--adopt` to take ownership of an unmanaged symlink with identical Skill bytes.
+Different bytes, directories, and broken links still block sync.
+Sync preserves the original source directory.
+
+Use a CLI containing `sync` to read lockfiles with recorded requirements.
+Older CLIs reject those fields.
+Keep legacy v2 stores separate; sync does not migrate their lockfiles.
+
+## Account login from an Agent
+
+Run `skilld auth login --no-browser --plain`.
+The CLI prints an authorization URL and waits for its loopback callback.
+Open that URL in the intended signed-in browser.
+The CLI stores the resulting credential through its normal credential store.
+Never copy browser cookies or tokens into a declaration.

package/dist/skills.d.mts

@@ -1,7 +1,12 @@
 import { HarnessV1Skill } from "@ai-sdk/harness";
-export declare function harnessSkillNames(): Promise<ReadonlyArray<string>>;
-export declare function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>>;
-export declare function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill>;
+export declare function harnessSkillNames(roots?: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+export declare function skilldMaintainedSkillNames(roots?: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+/**
+ * Loads one skilld-maintained Skill. A Harness Skill also carries every supporting file
+ * in its folder, nested `scripts/` and `references/` folders included, so the Agent can read them.
+ * `roots` lists the folders to search, first match wins.
+ */
+export declare function loadSkilldMaintainedSkill(name: string, roots?: ReadonlyArray<string>): Promise<HarnessV1Skill>;
 export declare const DEFAULT_OUTPUT_POLICY: Readonly<{
   maxSourceFiles: 2000;
   maxSourceFileBytes: number;

package/dist/skills.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";wBAsDsB,qBAAqB,QAAQ;wBAK7B,8BAA8B,QAAQ;wBAKtC,0BAA0B,eAAe,QAAQ;qBAqB1D,uBAAqB"}
+{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";wBAmEsB,kBAAkB,QAAO,wBAAqC,QAAQ;wBAKtE,2BAA2B,QAAO,wBAAqC,QAAQ;;;;;;wBAU/E,0BAA0B,cAAc,QAAO,wBAAqC,QAAQ;qBAyBrG,uBAAqB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",
@@ -49,7 +49,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@ai-sdk/harness": "^1.0.100",
+    "@ai-sdk/harness": "^1.0.128",
     "yaml": "^2.9.0",
     "zod": "^4.5.4"
   },
@@ -69,7 +69,7 @@
     "build": "obuild && node scripts/copy-skilld-maintained-skills.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc6 --noEmit",
     "test": "vitest",
     "test:run": "vitest run",
     "publint": "publint",