skilld-harness 3.3.0 → 3.4.0

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

@@ -93,6 +93,22 @@ Good: `Add and debug Schema.org JSON-LD in Nuxt with nuxt-schema-org. Use when a
 
 ## 4. Check and report
 
+### Cross-Agent portability
+
+Keep one source Skill for compatible Agents. Keep their discovery paths outside the generated Skill.
+Use capability descriptions instead of provider-specific tool names.
+Ask for inputs explicitly; do not depend on `$ARGUMENTS`, hooks, or dynamic context injection.
+Resolve bundled files from the Skill directory and consumer commands from the consumer project root.
+Name script runtimes, binaries, network access, and credential requirements beside their use.
+If a required capability is unavailable, report it and stop that dependent step.
+Never invent evidence or silently skip a required check.
+
+Check a matching task, an unrelated task, and a missing-input task.
+When available, use a fresh session in each Agent the user asks to support.
+Record its version, model, task, output, and required permissions.
+Distinguish format validation, discovery, activation, and task completion.
+Report unavailable Agent paths untested. Package example checks do not prove cross-Agent execution.
+
 Before finishing, confirm:
 
 - Each example ran against the recorded version, or is reported untested.

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

@@ -59,6 +59,26 @@ 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.

package/dist/skills/skilld/SKILL.md

@@ -14,7 +14,8 @@ Run a Skill first. Install a Skill only when the user asks to keep it.
 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`.
-The other commands do not support JSON output.
+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.
@@ -26,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:

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",
@@ -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",