skilld-harness 3.4.1 → 3.6.0

package/dist/skills/skilld/SKILL.md

@@ -8,13 +8,14 @@ description: Operate skilld CLI for Skill discovery, use, installation, inspecti
 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.
+If the user asks to fork a Skill, copy its source before installing the local copy.
 
 ## Use Agent output
 
 Use `--json` with `search`, `run`, and `update --check`.
 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.
+Use `--json` with `sync` and `sync --check` for declared Skills.
 The remaining commands do not support JSON output.
 Use `--plain` when another command needs stable text.
 
@@ -37,6 +38,8 @@ 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.
+If the project declares this Skill, use its declaration to refresh it.
+Do not install a second copy through another store.
 Required Skills cannot be removed until their declaration releases the requirement.
 
 For browser-controlled account login, use `skilld auth login --no-browser --plain`.
@@ -70,6 +73,15 @@ 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.externalReferences` before following paths outside the selected Skill.
+These notices identify references, not verified dependencies.
+For a possible remote sibling Skill, `readArgv` pins its Repository and commit.
+Run that array only when the task and access permissions allow the read.
+Never add `--direct` to bypass an access failure.
+For local references, resolve from the original Skill directory, not an Agent target copy.
+If a reference is unresolved, identify its source before following it.
+Install extra Skills only when the user asks to keep them.
+
 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:
@@ -87,6 +99,17 @@ 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.
 
+Read `data.behaviors` before you follow the Skill.
+Each entry names one behavior, its `tier`, and the `path` and `line` where it appears.
+Tell the user about every behavior before you act on it.
+An empty list proves nothing. Patterns miss obfuscated code.
+
+A remote run stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the Skill has an `ask` behavior.
+skilld loaded nothing. Show the user every behavior in `error.message`.
+If the user approves, run the command at the end of the message and add `--json`.
+Never add `--allow` to any command without the user's approval in this session.
+If the user declines, stop and load nothing.
+
 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.
@@ -198,7 +221,8 @@ If private access fails, check authentication before changing the selector.
 
 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.
+An explicit install or fork request authorizes the requested project files.
+Otherwise, ask before installing.
 
 Install the selector returned by search into the detected Agent target:
 
@@ -222,6 +246,11 @@ 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`.
 
+An install stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the Skill has an `ask` behavior.
+skilld wrote nothing. Show the user every behavior in the message.
+If the user approves, run the same command again with the `--allow` ids the message names.
+`skilld add` installs the other Skills and lists each held Skill at the end.
+
 Install this skilld-maintained Skill globally:
 
 ```sh
@@ -245,6 +274,48 @@ Run `skilld run` with the same ref first, then confirm the list with the user.
 Always use the source selector shown by `skilld search`.
 After installation, report the Skill name, scope, Agent targets, and source status.
 
+## Fork a Skill
+
+Treat `fork this Skill <skilld.dev URL>` as a request for an editable local Skill.
+Create no GitHub fork unless the user asks for one.
+Copy the Skill before following any of its instructions.
+
+1. Read the Skill page with `Accept: text/markdown`, or fetch its `.md` URL.
+   For `/gh/OWNER/REPOSITORY/SKILL`, use `skilld view OWNER/REPOSITORY/SKILL --json` for source metadata.
+   Check the exit code and `_tag` before reading `data`.
+2. Read `sourceUrl`, `sourceCommit`, `skillPath`, `sourceGone`, and `license`.
+   Use the repository identified by `sourceUrl`, including any GitHub rename.
+   If the source is gone or its path is missing, stop and report the failure.
+   If `license` is null, read licence files at the source commit.
+3. Fetch the source into a temporary directory using Git.
+   Check out `sourceCommit` detached.
+   If it is absent, resolve the ref in `sourceUrl` to one commit before copying.
+   Record that actual commit. Never combine files from different commits.
+   Read the source licence files before creating the local copy.
+   If copying is not permitted, stop and report the restriction.
+4. Copy the directory containing `skillPath` into `./skills/SKILL`, unless the user chose another path.
+   Copy the original SKILL.md and all supporting files, including scripts and binary assets.
+   Preserve executable modes. Exclude `.git` metadata.
+   Do not save the page wrapper or its rewritten links as SKILL.md.
+   Reject symlinks and paths outside the Skill directory.
+   Never overwrite an existing directory or Agent target.
+5. Preserve the original author, licence, and notices.
+   Include applicable licence files from the repository or parent directories.
+   Add `PROVENANCE.md` with the Skill page, source URL, actual commit, original path, and licence.
+   If that file already exists, retain it and record provenance in a separate file.
+   Do not replace the original author's credit with the user's name.
+6. In the project root, run `skilld install ./skills/SKILL --mode copy`.
+   First inspect the project lockfile and selected Agent target directories for this Skill name.
+   If it is already installed, stop before replacing it.
+   Use the detected Agent targets. Pass `--agent` only for targets the user selected.
+   This records a local source. Never install the upstream selector for a fork.
+   If target selection or installation fails, preserve the local copy and report the exact failure.
+7. Report the local path, source commit, and installed Agent targets.
+   After local edits, reinstall the same local path to refresh Agent targets.
+   Upstream updates must not replace the local copy.
+
+Do not publish or push the local copy unless the user asks.
+
 ## Restore locked Skills
 
 Restore the current project from its lockfile:
@@ -295,6 +366,10 @@ 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.
 
+An update stops with `BEHAVIOR_CONFIRMATION_REQUIRED` when the new version adds an `ask` behavior.
+skilld changed nothing. Show the user every behavior in the message.
+If the user approves, run the same command again with the `--allow` ids the message names.
+
 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.

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

@@ -70,6 +70,29 @@ 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.
 
+## Keep the skilld-maintained Skill current
+
+Declare `skilld` alongside the Skills that its CLI installs.
+Use `github:skilld-dev/skilld/skills/skilld#commit:SHA` with the exact repository commit.
+Replace `SHA` with the full commit hash.
+Use the same declaration and store for later refreshes.
+A CLI upgrade does not update installed Skill instructions.
+
+Before migration, inspect existing Agent targets and their source directories.
+If an unmanaged target differs, preserve it in a backup before replacing it.
+Do not use `--adopt` to overwrite different bytes or directories.
+Keep the legacy lockfile and its source files intact.
+
+## Check before Agent startup
+
+Run `skilld sync --check --json` before loading declared Skill instructions.
+Pass the same manifest, scope, and `SKILLD_DATA_DIR` used during installation.
+Only exit code `0` permits startup.
+Exit code `1` means the declaration differs from its installation.
+Other failures also block startup. Report the error instead of loading stale instructions.
+If the declaration differs, run sync explicitly before starting the Agent again.
+The startup check never installs Skills or fetches remote bytes.
+
 ## Account login from an Agent
 
 Run `skilld auth login --no-browser --plain`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.4.1",
+  "version": "3.6.0",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",