skilld-harness 3.6.3 → 3.6.5

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

@@ -13,15 +13,19 @@ The reader knows the language, the framework, and the domain. Write only what it
 Take a package name, directory, or prepared source. Ask for the destination only when it is missing.
 In a monorepo, put the Skill in the published package directory.
 Write one Skill per installed package, unless a second package has distinct users.
+Skip an internal package, whose users are the repository's own packages, such as a shared engine or types package. Report why, and write nothing.
 `assets/` holds the Harness request. A direct run ignores it.
 
 ## 1. Research
 
-1. Record the exact package version.
+1. Record the exact version the destination branch publishes: its `package.json` version and the npm dist-tag that carries it.
+   If npm `latest` is an older major, test the branch's version. If the branch is ahead of its last release, read source at that release tag and report the unreleased changes.
 2. Read the manifest, every exported entry point, and the public types.
+   For many sibling integrations, read the shared runtime and the most used few, and report which you sampled.
 3. For a framework module, read what setup registers: auto-imports, components, the config key and defaults, hooks, server routes.
 4. If the package wraps, re-exports, or peers on another package, read the types or tagged source of the version the consumer gets, never a default branch.
 5. Read the current official docs and examples, and release notes only for breaking changes and removed APIs.
+   When docs cover several frameworks, read the consumer's framework pages first, then the core pages they link.
 
 Test an existing Skill's claims; do not copy its layout.
 
@@ -32,18 +36,26 @@ Observed behaviour beats documentation.
 1. Create a minimal consumer fixture outside the package source. Install the recorded version, or link the local build.
    Before packing, build the package and its native code (NAPI, WASM); `prepack` can need them.
    Pack with the repository's package manager: `npm pack` leaves pnpm `catalog:` versions.
-   Install only the package and documented peers. A resolution error is a finding.
+   Give the fixture its own `pnpm-workspace.yaml`, so a parent workspace cannot satisfy its imports.
+   Install only the package, documented peers, and check tools such as `typescript`. A resolution error is a finding.
+   Install each peer at npm `latest`. If `latest` is outside the peer range, test both versions.
 2. Use consumer defaults. The package repository's config and fixtures can turn them off.
    In Nuxt, keep test modules out of `modules/`; Nuxt registers every module there.
    One fixture page can exercise many examples.
 3. Run each example you include. Compare output with the claim: HTML, return values, type errors, build logs, exit codes, report files.
-   Test each mode: framework modes, export conditions (`node`, `workerd`, `edge-light`, `browser`, CDN or IIFE build), and each CLI binary with a config file and with flags.
+   Each concrete claim in prose is an example too: a value, count, default, result shape, error text, exit code, or bundle effect. Run it, or report it read from source.
+   Run each example with one failure input as well, such as an unreachable URL, a bad token, or a stalled request.
+   Run each example under each global setting the Skill describes, such as a staging environment or a site-wide switch.
+   For each claim that a setting or dependency is required, run once without it and record what fails.
+   Test each mode the package declares: framework modes (SSR, SPA, streaming, dev, build), each condition in `exports`, the oldest runtime in `engines`, and each CLI binary with a config file and with flags. Report other modes untested.
    Wrap every run in `timeout 120`.
    Grep the package for agent and CI detection, such as `CLAUDECODE` or `CI`; unset each variable it reads with `env -u VAR`.
    Read dev warnings in the dev log, prerender results in build output, and runtime results from the production server.
    If a trap says nothing happens, run it and confirm the silence.
    To fetch from a server, run [scripts/serve-fixture.mjs](scripts/serve-fixture.mjs) in the fixture: `node SKILL_DIR/scripts/serve-fixture.mjs --fetch / -- node .output/server/index.mjs`.
-   For a binary, use `--fetch-raw PATH --out DIR`. `DIR/responses.json` lists each status and content type.
+   Quote `'{port}'` in a server argument, since some shells expand it. `--header 'User-Agent: Googlebot/2.1'` sends a header, `Host` included.
+   For a binary, use `--fetch-raw PATH --out DIR`. `DIR/responses.json` lists each status, content type, and response headers.
+   For an HTTP client package, start a fake target on port 0 inside the test, and assert on the requests it receives.
    Without `--fetch`, it holds the server until SIGTERM. Background it with your tool's option; `&` and `nohup` die with the shell call.
    Never kill by port or with `pkill -f`: another Agent can own that process.
    In a browser, set a desktop user agent; a package can treat `HeadlessChrome` as a bot.
@@ -77,19 +89,23 @@ Shape:
 - Name the package and tested version in the first paragraph, not the frontmatter.
 - Order, dropping empty sections: setup, automatic behaviour, common tasks, integrations, traps, version limits, config, debug.
 - A config example that is a common task goes there; the config section only lists options.
-- Write each code block as a complete module with imports. ESLint can lint fenced code.
+- Write each code block as a complete file with the imports the framework accepts. Start it with a path comment, such as `// server/api/search.ts`, so it can be extracted.
+- Write the tested version once, in the first paragraph. Other version literals, such as a User-Agent string, go stale.
 - A trap detailed in a reference gets one linking line in traps.
 - Aim for 150 lines and about 2,000 tokens in `SKILL.md`. Never exceed 500 lines.
+  Past the aim, keep silent failures before loud ones and common-path traps before rare ones. Merge traps that share a fix. Cut a common-task example before a trap.
 - Keep one file. Move a topic to `references/<topic>.md` only past about 40 lines and when under a third of tasks need it.
 - Link each reference from `SKILL.md`, one level deep. A reference over 100 lines starts with contents.
 - Write at most eight reference files. Add `scripts/` only when running code beats reading it.
+- Skillgen maintains only `SKILL.md` and Markdown under `references/`: at most 9 files and 64 KiB in total. It never updates `scripts/`.
 - Never include credentials, caches, build output, or dependency directories.
 
 The frontmatter contains only `name` and `description`.
 The name uses lowercase letters, numbers, and single hyphens, at most 64 characters, and matches the directory.
 For a scoped package, drop the `@` and replace `/` with a hyphen: `@nuxtjs/seo` becomes `nuxtjs-seo`.
 The description, at most 1024 characters in third person, says what the Skill does, then when to use it, in the words a user types: package name, main exports, config key, error symptoms.
-Good: `Add and debug Schema.org JSON-LD in Nuxt with nuxt-schema-org. Use when a task mentions structured data, rich results, useSchemaOrg, defineArticle, or the schemaOrg config key.`
+Write it as one plain line of 300 to 450 characters. Skill loaders parse frontmatter with different YAML parsers, so use no double quotes, backticks, or `%`. Name an error symptom in plain words, never as a quoted message.
+Good: `Adds and debugs Schema.org JSON-LD in Nuxt with nuxt-schema-org. Use when a task mentions structured data, rich results, useSchemaOrg, defineArticle, or the schemaOrg config key.`
 
 ## 4. Check and report
 
@@ -105,24 +121,33 @@ 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.
+If the user names no Agent, validate the format with `skilld run SKILL_DIR --json` and expect `_tag: Success`. Test the current Agent if it can start a fresh session.
 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:
+Before finishing, extract every block with [scripts/extract-blocks.mjs](scripts/extract-blocks.mjs): `node SKILL_DIR/scripts/extract-blocks.mjs SKILL.md DIR`.
+Copy each block into the fixture and run it unchanged. Never test a copy you edited by hand. Repeat after each edit.
+`--replace https://example.com=http://localhost:PORT` swaps a placeholder. `DIR/blocks.json` maps each block to its line.
+
+Confirm:
 
 - Each example ran against the recorded version, or is reported untested.
 - Each reference is linked. Delete stale files from an earlier Skill.
-- The frontmatter follows the rules above.
+- The frontmatter follows the rules above, parses with a strict YAML parser, and `skilld run SKILL_DIR --json` returns `_tag: Success`. Fix each failure before you finish.
 
 Report to the user:
 
 - The files and the tested version.
 - Each untested example, and each mismatch: example, documented result, observed result. These are package bugs.
+  Draft them as one issue for the package Repository, ordered by impact: silent wrong results, crashes, doc mismatches, cleanups.
+  Give each item expected, observed, a minimal repro with its output, and a source link at the release tag. File it only if asked.
 - The source path or documentation URL behind each version-specific rule.
-- If the package ships the Skill, add its directory to `files` in `package.json`. After one build, list packed files with `npm pack --dry-run --ignore-scripts`; `pnpm pack` rejects that flag.
-- Replace any README or docs `skilld add <package>` tip in place with the tip below. Add the badge after the others.
-  Replace `OWNER`, `REPOSITORY`, and `PACKAGE`. If the Repository has several Skills, add `/SKILL` to the page and badge paths. The skilld.dev indexer skips `SKILL.md` under test and fixture folders. The README omits the run command; the page shows it.
+- If the Skill sits inside the published package directory, add its directory to `files` in `package.json`. After one build, list packed files with `npm pack --dry-run --ignore-scripts`; `pnpm pack` rejects that flag.
+- Edit the README beside the Skill's `package.json`. If it already links the skilld.dev page, keep that link. Else add the badge below after the others.
+  Replace a `skilld add` tip that names this package in place with the tip below. Else add the tip after the install command.
+  Replace `OWNER`, `REPOSITORY`, and `PACKAGE`. Count every `SKILL.md` in the Repository, hidden Agent folders included; the skilld.dev indexer skips test and fixture folders.
+  If it holds several Skills, append `/SKILL_NAME` to the page and badge paths. The README omits the run command; the page shows it.
 
 ```html
 <a href="https://skilld.dev/gh/OWNER/REPOSITORY">

package/dist/skills/generate-package-skill/assets/harness-request.md

@@ -10,5 +10,7 @@ Use only the visible prepared source and cited official documentation.
 Pin external documentation to the dependency versions in the prepared manifest.
 If the session cannot run an example, list it as untested in your final message.
 List each documentation and behaviour mismatch in your final message.
-Write no files outside `{{OUTPUT_PATH}}`.
+Write no files outside `{{OUTPUT_PATH}}`. Build fixtures in a scratch directory outside it.
+Write only `SKILL.md` and Markdown files under `references/`: at most 9 files and 64 KiB in total. Skillgen rejects other output.
 Finish only after checking every output rule in this Skill.
+After you finish, the Harness checks the output. It returns each failed check to you; fix them in place.

package/dist/skills/generate-package-skill/scripts/extract-blocks.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// Write each fenced code block of a Skill file to its own directory, so every example runs exactly as written.
+//
+// Usage: node extract-blocks.mjs FILE OUT_DIR [--replace FROM=TO]...
+//
+// Block N goes to OUT_DIR/N/. A first line that names a path, such as `// server/api/search.ts`,
+// `# scripts/check.sh`, or `<!-- app/pages/index.vue -->`, sets the file name. Otherwise the file is `block.EXT`.
+// `--replace` swaps a placeholder in every block, such as `https://example.com=http://localhost:3000`.
+// OUT_DIR/blocks.json lists each block with its number, start line, language, and file.
+// The script refuses a path that leaves OUT_DIR. It never runs a block.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path'
+import process from 'node:process'
+
+function usage(message) {
+  process.stderr.write(`${message}\nUsage: node extract-blocks.mjs FILE OUT_DIR [--replace FROM=TO]...\n`)
+  process.exit(2)
+}
+
+const EXTENSIONS = { javascript: 'js', typescript: 'ts', shell: 'sh', bash: 'sh', zsh: 'sh', console: 'sh', yml: 'yaml', jsonc: 'json', markdown: 'md' }
+// A path comment: `// a/b.ts`, `# a/b.sh`, `-- a.sql`, `/* a.css */`, or `<!-- a.vue -->`. The path needs an extension.
+const PATH_COMMENT = /^\s*(?:\/\/|#|--|\/\*|<!--)\s*([\w@.\-/[\]]+\.\w+)\s*(?:(?:\*\/|-->)\s*)?$/
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})\s*([\w+-]*)/
+
+function parseArgs(argv) {
+  const [file, out, ...rest] = argv
+  if (!file || !out)
+    usage('Give the Skill file and an output directory.')
+  const replacements = []
+  for (let index = 0; index < rest.length; index++) {
+    if (rest[index] !== '--replace' || rest[index + 1] === undefined)
+      usage(`Unknown option: ${rest[index]}`)
+    const pair = rest[++index]
+    const split = pair.indexOf('=')
+    if (split <= 0)
+      usage('--replace needs FROM=TO.')
+    replacements.push([pair.slice(0, split), pair.slice(split + 1)])
+  }
+  return { file, out, replacements }
+}
+
+/** Fenced blocks with the line their content starts on. Nested shorter fences stay inside the block. */
+function fencedBlocks(markdown) {
+  const lines = markdown.split('\n')
+  const blocks = []
+  for (let index = 0; index < lines.length; index++) {
+    const open = FENCE_OPEN.exec(lines[index])
+    if (!open)
+      continue
+    const [, fence, lang] = open
+    const start = index + 1
+    let end = start
+    while (end < lines.length && !new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(lines[end]))
+      end++
+    blocks.push({ line: start + 1, lang: lang.toLowerCase(), body: lines.slice(start, end).join('\n') })
+    index = end
+  }
+  return blocks
+}
+
+function fileFor(block) {
+  const named = PATH_COMMENT.exec(block.body.split('\n')[0] ?? '')?.[1]
+  if (named) {
+    const path = normalize(named)
+    if (isAbsolute(path) || path === '..' || path.startsWith(`..${sep}`))
+      return { _tag: 'Escapes', path: named }
+    return { _tag: 'Named', path }
+  }
+  return { _tag: 'Default', path: `block.${EXTENSIONS[block.lang] ?? (block.lang || 'txt')}` }
+}
+
+const { file, out, replacements } = parseArgs(process.argv.slice(2))
+const markdown = await readFile(file, 'utf8').catch(error => usage(`Cannot read ${file}: ${error.message}`))
+const manifest = []
+let status = 0
+for (const [index, block] of fencedBlocks(markdown).entries()) {
+  const number = index + 1
+  const target = fileFor(block)
+  if (target._tag === 'Escapes') {
+    process.stderr.write(`block ${number} line ${block.line}: path ${target.path} leaves the output directory; skipped\n`)
+    status = 1
+    continue
+  }
+  const content = replacements.reduce((text, [from, to]) => text.replaceAll(from, to), block.body)
+  const destination = join(out, String(number), target.path)
+  await mkdir(dirname(destination), { recursive: true })
+  await writeFile(destination, content.endsWith('\n') ? content : `${content}\n`)
+  manifest.push({ block: number, line: block.line, lang: block.lang, file: join(String(number), target.path) })
+  process.stderr.write(`block ${number} line ${block.line} ${block.lang || '-'} -> ${join(String(number), target.path)}\n`)
+}
+await mkdir(out, { recursive: true })
+await writeFile(join(out, 'blocks.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+process.exit(status)

package/dist/skills/generate-package-skill/scripts/serve-fixture.mjs

@@ -1,25 +1,27 @@
 #!/usr/bin/env node
 // Start a fixture server on a free port, fetch paths, then stop its whole process group.
 //
-// Usage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...
+// Usage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--header 'NAME: VALUE']... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...
 //
 // The script replaces `{port}` in each argument and sets PORT, NITRO_PORT, and NUXT_PORT.
 // It prints `ready http://localhost:PORT` on stderr when the server answers.
 // `--fetch` asks for HTML. `--fetch-raw` asks for any type, such as an image, and needs `--out`.
+// `--header` sends a request header with every fetch, such as `Host` or `User-Agent`. Node `fetch` drops `Host`; this script does not.
 // Each fetch prints `GET PATH STATUS CONTENT-TYPE BYTES` on stderr. The body goes to stdout, or to DIR when `--out` is set.
-// With `--out`, DIR/responses.json lists each path with its file, status, content type, and byte count.
+// With `--out`, DIR/responses.json lists each path with its file, status, content type, byte count, and response headers.
 // Without `--fetch`, or with `--hold`, the server stays up until the hold time ends, the script gets SIGTERM, or its parent exits.
 // The script never kills by port or by name. It stops only the process group it started. POSIX only.
 
 import { spawn } from 'node:child_process'
 import { mkdir, writeFile } from 'node:fs/promises'
+import { request as httpRequest } from 'node:http'
 import { createServer } from 'node:net'
 import { join } from 'node:path'
 import process from 'node:process'
 import { setTimeout as delay } from 'node:timers/promises'
 
 function usage(message) {
-  process.stderr.write(`${message}\nUsage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...\n`)
+  process.stderr.write(`${message}\nUsage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--header 'NAME: VALUE']... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...\n`)
   process.exit(2)
 }
 
@@ -31,7 +33,7 @@ function parseSeconds(flag, value) {
 }
 
 function parseArgs(argv) {
-  const options = { fetch: [], out: undefined, hold: undefined, timeout: 120, command: [] }
+  const options = { fetch: [], headers: {}, out: undefined, hold: undefined, timeout: 120, command: [] }
   for (let index = 0; index < argv.length; index++) {
     const flag = argv[index]
     if (flag === '--') {
@@ -41,16 +43,28 @@ function parseArgs(argv) {
     const value = argv[++index]
     if (value === undefined)
       usage(`${flag} needs a value.`)
-    if (flag === '--fetch' || flag === '--fetch-raw')
+    if (flag === '--fetch' || flag === '--fetch-raw') {
       options.fetch.push({ path: value.startsWith('/') ? value : `/${value}`, raw: flag === '--fetch-raw' })
-    else if (flag === '--out')
+    }
+    else if (flag === '--header') {
+      const split = value.indexOf(':')
+      const name = split > 0 ? value.slice(0, split).trim().toLowerCase() : ''
+      if (!name || !value.slice(split + 1).trim())
+        usage('--header needs NAME: VALUE, such as \'User-Agent: Googlebot/2.1\'.')
+      options.headers[name] = value.slice(split + 1).trim()
+    }
+    else if (flag === '--out') {
       options.out = value
-    else if (flag === '--hold')
+    }
+    else if (flag === '--hold') {
       options.hold = parseSeconds(flag, value)
-    else if (flag === '--timeout')
+    }
+    else if (flag === '--timeout') {
       options.timeout = parseSeconds(flag, value)
-    else
+    }
+    else {
       usage(`Unknown option: ${flag}`)
+    }
   }
   if (options.command.length === 0)
     usage('Give the server command after --.')
@@ -168,13 +182,10 @@ async function waitUntilReady({ path, raw }) {
   while (Date.now() < deadline) {
     if (exited)
       return { _tag: 'Exited' }
-    const response = await fetch(`${origin}${path}`, { headers: { accept: raw ? '*/*' : 'text/html' }, signal: AbortSignal.timeout(Math.max(deadline - Date.now(), 1)) })
+    const response = await get(path, raw, Math.max(deadline - Date.now(), 1))
       .catch(() => undefined) // Connection refused while the server starts. Retry until the deadline.
-    if (response && ![502, 503, 504].includes(response.status)) {
-      await response.body?.cancel()
+    if (response && ![502, 503, 504].includes(response.status))
       return { _tag: 'Ready' }
-    }
-    await response?.body?.cancel()
     await delay(500)
   }
   return { _tag: 'TimedOut' }
@@ -182,16 +193,29 @@ async function waitUntilReady({ path, raw }) {
 
 const responses = []
 
+// node:http, because `fetch` silently replaces a `Host` header with the origin's host.
+function get(path, raw, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(`${origin}${path}`, { headers: { accept: raw ? '*/*' : 'text/html', ...options.headers }, signal: AbortSignal.timeout(timeoutMs) }, (response) => {
+      const chunks = []
+      response.on('data', chunk => chunks.push(chunk))
+      response.once('error', reject)
+      response.once('end', () => resolve({ status: response.statusCode, headers: response.headers, body: Buffer.concat(chunks) }))
+    })
+    req.once('error', reject)
+    req.end()
+  })
+}
+
 async function fetchPath({ path, raw }) {
-  const response = await fetch(`${origin}${path}`, { headers: { accept: raw ? '*/*' : 'text/html' }, signal: AbortSignal.timeout(options.timeout * 1000) })
-  const body = Buffer.from(await response.arrayBuffer())
-  const contentType = response.headers.get('content-type')
-  process.stderr.write(`GET ${path} ${response.status} ${contentType ?? '-'} ${body.byteLength}\n`)
+  const { status, headers, body } = await get(path, raw, options.timeout * 1000)
+  const contentType = headers['content-type'] ?? null
+  process.stderr.write(`GET ${path} ${status} ${contentType ?? '-'} ${body.byteLength}\n`)
   if (options.out) {
     const file = fileName(path, contentType)
     await mkdir(options.out, { recursive: true })
     await writeFile(join(options.out, file), body)
-    responses.push({ path, file, status: response.status, contentType, bytes: body.byteLength })
+    responses.push({ path, file, status, contentType, bytes: body.byteLength, headers })
     await writeFile(join(options.out, 'responses.json'), `${JSON.stringify(responses, null, 2)}\n`)
   }
   else {

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

@@ -18,12 +18,23 @@ Review the supplied Skill as an Agent would use it.
 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. If a runtime is available, run them and report each result that differs from the claim.
+   An example is each code block and each checkable prose claim: a default, a list, a count, error text, an exit code, or "X happens when Y".
+   Test the exact version the Skill names, never the repository head. Use the toolchain its users run, in each mode the claim covers, such as SSR, dev, and build.
+   Install it in an empty scratch directory with its own `pnpm-workspace.yaml`. Prefer a local fixture to a live site. Never use personal credentials.
+   For cloud-bound code, typecheck it and run it against in-memory stand-ins. Confirm a failing claim with a second probe before you report it.
+   Mark each example executed, read from source, or unverified.
 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.
+12. For a package Skill, confirm the body names the package version it was tested against, once, in the first paragraph. Flag other version literals.
+13. Confirm the body covers each export, option, or symptom the description promises.
 
-Rank each finding as `error`, `warning`, or `note`.
-Give the exact path and a direct fix.
+Rank each finding:
+
+- `error`: following the Skill gives a wrong result, a failure, or a security gap.
+- `warning`: an Agent would act wrongly on the claim, a failure stays silent, or a needed input is missing.
+- `note`: precision, repetition, structure, or token cost.
+
+Give the exact path, the line, and a direct fix.
 Do not rewrite the Skill unless the request asks for changes.
 
 For a direct run, present the findings to the user.

package/dist/skills/review-skill/assets/harness-request.md

@@ -4,7 +4,8 @@ Review the prepared Skill at `{{SOURCE_PATH}}`.
 Write the result to `{{OUTPUT_PATH}}/review.json`.
 
 Read this Skill fully before reviewing.
-Write no other output files.
+`{{OUTPUT_PATH}}` holds only `review.json`. Build fixtures in a scratch directory outside it.
+Start each `message` with the line it concerns, such as `Line 42:`.
 Use this JSON shape:
 
 ```json

package/dist/skills/skilld/SKILL.md

@@ -111,6 +111,8 @@ 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`.
+A match can carry a model reading, such as `(model reading: quoted example. REASON)`.
+Show it as a language model's reading. It never replaces the user's approval.
 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.
@@ -265,19 +267,28 @@ skilld install skilld --global
 Install every Skill a Repository, curator, or collection names:
 
 ```sh
-skilld add OWNER/REPOSITORY
-skilld add @LOGIN/SLUG --global
+skilld add OWNER/REPOSITORY --all
+skilld add @LOGIN/SLUG --all --global
 ```
 
 `skilld add` accepts `--global`, `--agent`, and `--mode` like `skilld install`.
 It prints one `Installed Skill` line per Skill.
-An Agent run installs every Skill the ref names. Pass `--all` to state that intent.
-A person at a terminal is asked which Skills to install.
-Run `skilld run` with the same ref first, then confirm the list with the user.
+If several Skills are listed, an Agent run requires `--all`.
+A normal terminal asks which Skills to install. `--plain` also requires `--all` for several Skills.
+One listed Skill installs without a picker. `add` does not support JSON output.
+Run `skilld run` with the same ref first, then confirm the list with the user before using `--all`.
 `skilld add` with one Skill selector installs that Skill like `skilld install`.
+Listing never requests registry indexing.
+Skills discovered through GitHub still use hosted delivery by default.
+If delivery fails, skilld shows an explicit direct installation command where possible.
+Only use direct installation when the user chooses it. Never use it to bypass a verification or policy failure.
+`skilld add OWNER/REPOSITORY --all --direct` lists and installs public GitHub files without skilld.dev.
+It records `unverified`. Curator and collection refs require hosted delivery.
+Behavior approval still applies.
+`skilld add ./PATH` installs one local Skill whose directory contains `SKILL.md`.
 
 Always use the source selector shown by `skilld search`.
-After installation, report the Skill name, scope, Agent targets, and source status.
+After installation, report the Skill name, scope, installed agent paths, and source status.
 
 ## Fork a Skill
 

package/package.json

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