From 2cf0d294ee27f60fbf0bab991a18746a397b2b9f Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 7 Oct 2026 13:20:01 +1100
Subject: [PATCH 1/2] feat(skills): add batch 3 package Skill rules from five
 runs

Five direct runs (@nuxtjs/robots, @nuxt/scripts, @unhead/vue, which-nuxt,
retriv) and their independent reviews found the same gaps. Every run
hand-wrote a code-block extractor. Most review findings came from prose
claims, which the Skill never called examples. One run tested npm latest
(1.x) while the branch published 2.0 betas. Node fetch dropped the Host
header the robots run needed. Reviewers had no definition of the three
finding levels.

Add extract-blocks.mjs, --header and response headers to serve-fixture,
an internal-package gate, the branch version rule, prose-claim and
failure-input checks, and defined review levels. The Harness requests now
state the Skillgen output shape and keep fixtures out of the output.
---
 .../harness/test/unit/extract-blocks.test.ts  | 75 +++++++++++++++
 .../harness/test/unit/serve-fixture.test.ts   | 21 +++++
 skills/generate-package-skill/SKILL.md        | 42 +++++++--
 .../assets/harness-request.md                 |  3 +-
 .../scripts/extract-blocks.mjs                | 94 +++++++++++++++++++
 .../scripts/serve-fixture.mjs                 | 62 ++++++++----
 skills/review-skill/SKILL.md                  | 17 +++-
 skills/review-skill/assets/harness-request.md |  3 +-
 8 files changed, 283 insertions(+), 34 deletions(-)
 create mode 100644 packages/harness/test/unit/extract-blocks.test.ts
 create mode 100644 skills/generate-package-skill/scripts/extract-blocks.mjs

diff --git a/packages/harness/test/unit/extract-blocks.test.ts b/packages/harness/test/unit/extract-blocks.test.ts
new file mode 100644
index 00000000..b8d56d3d
--- /dev/null
+++ b/packages/harness/test/unit/extract-blocks.test.ts
@@ -0,0 +1,75 @@
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const script = resolve(import.meta.dirname, '../../../../skills/generate-package-skill/scripts/extract-blocks.mjs')
+
+const skill = [
+  '# Example',
+  '',
+  '```ts',
+  '// server/api/search.ts',
+  'export default defineEventHandler(() => fetch(\'https://example.com/api\'))',
+  '```',
+  '',
+  '````md',
+  '```ts',
+  'nested',
+  '```',
+  '````',
+  '',
+  '```vue',
+  '<!-- app/pages/index.vue -->',
+  '<template><p>Hi</p></template>',
+  '```',
+  '',
+  '```sh',
+  'pnpm add retriv',
+  '```',
+  '',
+  '```ts',
+  '// ../outside.ts',
+  'export {}',
+  '```',
+  '',
+].join('\n')
+
+describe('extract-blocks script', () => {
+  let dir: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'extract-blocks-'))
+    await writeFile(join(dir, 'SKILL.md'), skill)
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('writes each block to its own directory under the path its first line names', async () => {
+    const out = join(dir, 'blocks')
+    const run = spawnSync(process.execPath, [script, join(dir, 'SKILL.md'), out, '--replace', 'https://example.com=http://localhost:4000'], { encoding: 'utf8' })
+
+    expect(await readFile(join(out, '1/server/api/search.ts'), 'utf8')).toBe('// server/api/search.ts\nexport default defineEventHandler(() => fetch(\'http://localhost:4000/api\'))\n')
+    expect(await readFile(join(out, '2/block.md'), 'utf8')).toBe('```ts\nnested\n```\n')
+    expect(await readFile(join(out, '3/app/pages/index.vue'), 'utf8')).toContain('<template>')
+    expect(await readFile(join(out, '4/block.sh'), 'utf8')).toBe('pnpm add retriv\n')
+    const manifest = JSON.parse(await readFile(join(out, 'blocks.json'), 'utf8'))
+    expect(manifest.map((entry: { block: number, line: number, file: string }) => [entry.block, entry.line, entry.file])).toEqual([
+      [1, 4, '1/server/api/search.ts'],
+      [2, 9, '2/block.md'],
+      [3, 15, '3/app/pages/index.vue'],
+      [4, 20, '4/block.sh'],
+    ])
+    expect(run.status).toBe(1)
+    expect(run.stderr).toContain('block 5 line 24: path ../outside.ts leaves the output directory; skipped')
+  })
+
+  it('refuses a replacement without a target', () => {
+    const run = spawnSync(process.execPath, [script, join(dir, 'SKILL.md'), join(dir, 'out'), '--replace', 'https://example.com'], { encoding: 'utf8' })
+
+    expect(run.status).toBe(2)
+    expect(run.stderr).toContain('--replace needs FROM=TO.')
+  })
+})
diff --git a/packages/harness/test/unit/serve-fixture.test.ts b/packages/harness/test/unit/serve-fixture.test.ts
index 36de09a2..9cae600c 100644
--- a/packages/harness/test/unit/serve-fixture.test.ts
+++ b/packages/harness/test/unit/serve-fixture.test.ts
@@ -12,6 +12,10 @@ import { writeFileSync } from 'node:fs'
 writeFileSync(process.argv[3], String(process.pid))
 process.on('SIGTERM', () => {})
 createServer((request, response) => {
+  if (request.url === '/echo') {
+    response.setHeader('x-robots-tag', 'noindex')
+    return response.end(request.headers.host + ' ' + request.headers['user-agent'])
+  }
   if (request.url === '/crash')
     return request.socket.destroy()
   if (request.url === '/logo.png') {
@@ -106,6 +110,23 @@ describe('serve-fixture script', () => {
     expect([...await readFile(join(out, response!.file))]).toEqual([0x89, 0x50, 0x4E, 0x47, 0x00, 0xFF, 0xFE])
   })
 
+  it('sends each --header, Host included, and records the response headers', async () => {
+    const out = join(dir, 'headers')
+    const run = await collect(spawn(process.execPath, [script, '--header', 'Host: staging.example.com', '--header', 'User-Agent: Googlebot/2.1', '--fetch', '/echo', '--out', out, '--', 'sh', wrapper, '{port}']))
+
+    expect(run.code).toBe(0)
+    const [response] = JSON.parse(await readFile(join(out, 'responses.json'), 'utf8')) as Array<{ file: string, headers: Record<string, string> }>
+    expect(await readFile(join(out, response!.file), 'utf8')).toBe('staging.example.com Googlebot/2.1')
+    expect(response!.headers['x-robots-tag']).toBe('noindex')
+  })
+
+  it('refuses a header without a name and value', async () => {
+    const run = await collect(spawn(process.execPath, [script, '--header', 'Host', '--fetch', '/', '--', 'sh', wrapper, '{port}']))
+
+    expect(run.code).toBe(2)
+    expect(run.stderr).toContain('--header needs')
+  })
+
   it('refuses a raw fetch without an output directory', async () => {
     const run = await collect(spawn(process.execPath, [script, '--fetch-raw', '/logo.png', '--', 'sh', wrapper, '{port}']))
 
diff --git a/skills/generate-package-skill/SKILL.md b/skills/generate-package-skill/SKILL.md
index f83a9c29..c1d5ecda 100644
--- a/skills/generate-package-skill/SKILL.md
+++ b/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,24 @@ 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.
+   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 +87,22 @@ 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.`
+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,11 +118,16 @@ 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.
@@ -119,10 +137,14 @@ 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">
diff --git a/skills/generate-package-skill/assets/harness-request.md b/skills/generate-package-skill/assets/harness-request.md
index b0fadcb8..e900f17a 100644
--- a/skills/generate-package-skill/assets/harness-request.md
+++ b/skills/generate-package-skill/assets/harness-request.md
@@ -10,5 +10,6 @@ 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.
diff --git a/skills/generate-package-skill/scripts/extract-blocks.mjs b/skills/generate-package-skill/scripts/extract-blocks.mjs
new file mode 100644
index 00000000..9f17c784
--- /dev/null
+++ b/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)
diff --git a/skills/generate-package-skill/scripts/serve-fixture.mjs b/skills/generate-package-skill/scripts/serve-fixture.mjs
index 1b224e41..82b0f511 100644
--- a/skills/generate-package-skill/scripts/serve-fixture.mjs
+++ b/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 {
diff --git a/skills/review-skill/SKILL.md b/skills/review-skill/SKILL.md
index dcf03563..c41b5457 100644
--- a/skills/review-skill/SKILL.md
+++ b/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.
diff --git a/skills/review-skill/assets/harness-request.md b/skills/review-skill/assets/harness-request.md
index 6dc13632..ff840973 100644
--- a/skills/review-skill/assets/harness-request.md
+++ b/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

From c2009a8e5403611fe82eed5926c815e7d85b90f6 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 7 Oct 2026 13:47:35 +1100
Subject: [PATCH 2/2] feat(harness): return failed output checks to the Agent

A run whose output failed a deterministic check ended as InvalidSkill,
and the session was destroyed before the Agent saw why. The Agent still
held its context and could have fixed the issue in one turn. The Harness
now sends the issues back in the same session, up to two times.

The @unhead/vue Skill shipped a frontmatter description with quotes and %
that read as broken. The check now requires one plain YAML line without
double quotes, backticks, or %, and the Skill says so.
---
 packages/harness/README.md                    |   5 +-
 packages/harness/src/harness.ts               | 121 ++++++++++++------
 .../harness/src/internal/output/validate.ts   |  11 +-
 packages/harness/test/e2e/harness.test.ts     |   4 +-
 .../harness/test/e2e/output-checks.test.ts    |  54 ++++++++
 packages/harness/test/e2e/run-events.test.ts  |  11 +-
 skills/generate-package-skill/SKILL.md        |   5 +-
 .../assets/harness-request.md                 |   1 +
 8 files changed, 168 insertions(+), 44 deletions(-)

diff --git a/packages/harness/README.md b/packages/harness/README.md
index 3ea85263..06de37ab 100644
--- a/packages/harness/README.md
+++ b/packages/harness/README.md
@@ -48,11 +48,14 @@ Both `Ok` and `Err` carry a `report`, so a failed run still reports its cost.
 A token count is `undefined` when the adapter does not report it.
 If the run fails before the Agent starts, `steps` is 0.
 `report.warnings` names each source file the Harness left out for size, each `onEvent` failure, and each cleanup problem.
-An `InvalidSkill` error lists each failed output check in `issues`.
+If the output fails a check, the Harness sends the issues back to the Agent in the same session, up to two times.
+Each repair turn adds its steps and usage to the report, and a warning names the issues.
+An `InvalidSkill` error lists each check that still fails in `issues`.
 
 The Harness checks the rules that the generation Skills state:
 
 - The frontmatter contains only `name` and `description`.
+- The description is one plain YAML line without double quotes, backticks, or `%`.
 - `SKILL.md` links every file under `references/`, by a Markdown link or an inline code path.
 - A package Skill keeps `SKILL.md` under 500 lines and writes at most eight reference files.
 - A project Skill points only at project files and gives at least one search command.
diff --git a/packages/harness/src/harness.ts b/packages/harness/src/harness.ts
index 59f86787..4756a418 100644
--- a/packages/harness/src/harness.ts
+++ b/packages/harness/src/harness.ts
@@ -1,5 +1,5 @@
 import type { HarnessV1NetworkSandboxSession, HarnessV1Skill } from '@ai-sdk/harness'
-import type { SandboxSession } from './internal/output/collect.ts'
+import type { CollectedFile, SandboxSession } from './internal/output/collect.ts'
 import type { Result } from './internal/result.ts'
 import type { PreparedSource } from './internal/source/host.ts'
 import type { FetchClient } from './internal/source/npm.ts'
@@ -125,8 +125,23 @@ function toUsage(usage: AgentUsage): SkillRunUsage {
   }
 }
 
-function cancelled(): RunOutcome {
-  return err({ _tag: 'Cancelled', message: 'Skill run was cancelled.' })
+/** An unknown count in any turn keeps the total unknown. */
+function sumUsage(a: SkillRunUsage, b: SkillRunUsage): SkillRunUsage {
+  const sum = (x: number | undefined, y: number | undefined) => x === undefined || y === undefined ? undefined : x + y
+  return { inputTokens: sum(a.inputTokens, b.inputTokens), cachedInputTokens: sum(a.cachedInputTokens, b.cachedInputTokens), outputTokens: sum(a.outputTokens, b.outputTokens) }
+}
+
+/** Turns the Agent gets to fix output that failed the deterministic checks, in the same session. */
+const OUTPUT_REPAIR_TURNS = 2
+
+function repairRequest(outputPath: string, issues: ReadonlyArray<string>): string {
+  return [
+    `The Harness checked the output at \`${outputPath}\` and found these problems:`,
+    '',
+    ...issues.map(issue => `- ${issue}`),
+    '',
+    `Fix each problem in place. Write no files outside \`${outputPath}\`. Finish when the output passes these checks.`,
+  ].join('\n')
 }
 
 async function prepareCurrentSkill(destination: SkillDestination, policy: SkillOutputPolicy, signal?: AbortSignal): Promise<Result<PreparedSource | undefined, SkillRunError>> {
@@ -263,10 +278,14 @@ async function writePreparedSource(active: ActiveSandbox, prepared: PreparedRun,
   })
 }
 
-function toAgentError(cause: unknown, signal?: AbortSignal): RunOutcome {
+function agentError(cause: unknown, signal?: AbortSignal): SkillRunError {
   return signal?.aborted
-    ? cancelled()
-    : err({ _tag: 'AgentFailed', message: 'Harness Agent failed during the Skill run.', cause })
+    ? { _tag: 'Cancelled', message: 'Skill run was cancelled.' }
+    : { _tag: 'AgentFailed', message: 'Harness Agent failed during the Skill run.', cause }
+}
+
+function toAgentError(cause: unknown, signal?: AbortSignal): RunOutcome {
+  return err(agentError(cause, signal))
 }
 
 export function createSkillHarness(options: CreateSkillHarnessOptions): SkillHarness {
@@ -352,44 +371,70 @@ export function createSkillHarness(options: CreateSkillHarnessOptions): SkillHar
       const currentSkillPath = posix.join(active.workDir, 'input/current-skill')
       const outputPath = posix.join(active.workDir, 'skilld-output', prepared.outputName)
       const prompt = renderRequest(requestContent(skill), sourcePath, currentSkillPath, outputPath, prepared.outputName)
+      const outputSandbox = active.sandbox
+      // Steps count across turns, so a repair turn continues the numbering.
       let step = 0
-      const generated = await agent.generate({
-        session,
-        prompt,
-        abortSignal: signal,
-        onStepStart: (event) => {
-          step = event.stepNumber
-          log.emit({ _tag: 'StepStart', step })
-        },
-        onToolExecutionStart: ({ toolCall }) => {
-          log.emit({ _tag: 'ToolCall', step, toolName: toolCall.toolName, toolCallId: toolCall.toolCallId, input: toolCall.input })
-        },
-        onStepEnd: (result) => {
-          log.emit({ _tag: 'StepFinish', step: result.stepNumber, finishReason: result.finishReason, usage: toUsage(result.usage) })
-        },
-      }).then(ok, cause => err(cause))
-      if (generated._tag === 'Err')
-        return toAgentError(generated.error, signal)
-      log.settle(toUsage(generated.value.totalUsage), generated.value.steps.length)
-      if (signal?.aborted)
-        return cancelled()
+      let stepOffset = 0
+      let usage: SkillRunUsage | undefined
+      const turn = async (text: string): Promise<Result<void, SkillRunError>> => {
+        const generated = await agent.generate({
+          session,
+          prompt: text,
+          abortSignal: signal,
+          onStepStart: (event) => {
+            step = stepOffset + event.stepNumber
+            log.emit({ _tag: 'StepStart', step })
+          },
+          onToolExecutionStart: ({ toolCall }) => {
+            log.emit({ _tag: 'ToolCall', step, toolName: toolCall.toolName, toolCallId: toolCall.toolCallId, input: toolCall.input })
+          },
+          onStepEnd: (result) => {
+            log.emit({ _tag: 'StepFinish', step: stepOffset + result.stepNumber, finishReason: result.finishReason, usage: toUsage(result.usage) })
+          },
+        }).then(ok, cause => err(cause))
+        if (generated._tag === 'Err')
+          return err(agentError(generated.error, signal))
+        const turnUsage = toUsage(generated.value.totalUsage)
+        usage = usage ? sumUsage(usage, turnUsage) : turnUsage
+        stepOffset += generated.value.steps.length
+        log.settle(usage, stepOffset)
+        return signal?.aborted ? err({ _tag: 'Cancelled', message: 'Skill run was cancelled.' }) : ok(undefined)
+      }
+      const check = async (): Promise<Result<ReadonlyArray<CollectedFile>, SkillRunError>> => {
+        const collected = await collectSandboxOutput(outputSandbox, outputPath, policy, signal)
+        if (collected._tag === 'Err')
+          return collected
+        const validated = prepared.skillName === 'review-skill'
+          ? validateSkillReview(collected.value)
+          : validateGeneratedSkill(
+              prepared.outputName,
+              collected.value,
+              prepared.skillName === 'generate-project-skill'
+                ? { _tag: 'ProjectSkill', projectPaths: prepared.source.files.map(file => file.path) }
+                : { _tag: 'PackageSkill' },
+            )
+        return validated._tag === 'Err' ? validated : ok(collected.value)
+      }
 
-      const collected = await collectSandboxOutput(active.sandbox, outputPath, policy, signal)
-      if (collected._tag === 'Err')
-        return collected
+      const first = await turn(prompt)
+      if (first._tag === 'Err')
+        return first
+      let checked = await check()
+      // A failed check goes back to the Agent, which still holds its context, instead of failing the run.
+      for (let repair = 1; repair <= OUTPUT_REPAIR_TURNS && checked._tag === 'Err' && checked.error._tag === 'InvalidSkill'; repair++) {
+        log.warn(`Output checks failed; repair turn ${repair} of ${OUTPUT_REPAIR_TURNS}: ${checked.error.issues.join(' ')}`)
+        const repaired = await turn(repairRequest(outputPath, checked.error.issues))
+        if (repaired._tag === 'Err')
+          return repaired
+        checked = await check()
+      }
+      if (checked._tag === 'Err')
+        return checked
+      const collected = checked
 
       if (prepared.skillName === 'review-skill')
         return validateSkillReview(collected.value)
 
-      const validated = validateGeneratedSkill(
-        prepared.outputName,
-        collected.value,
-        prepared.skillName === 'generate-project-skill'
-          ? { _tag: 'ProjectSkill', projectPaths: prepared.source.files.map(file => file.path) }
-          : { _tag: 'PackageSkill' },
-      )
-      if (validated._tag === 'Err')
-        return validated
       if (!prepared.destination)
         return err({ _tag: 'InvalidInput', message: 'Skill destination is required.' })
       const promoted = await promoteSkill(
diff --git a/packages/harness/src/internal/output/validate.ts b/packages/harness/src/internal/output/validate.ts
index e24ae5dc..76b1c77f 100644
--- a/packages/harness/src/internal/output/validate.ts
+++ b/packages/harness/src/internal/output/validate.ts
@@ -1,7 +1,7 @@
 import type { SkillReview, SkillReviewFinding, SkillRunError } from '../../types.ts'
 import type { Result } from '../result.ts'
 import type { CollectedFile } from './collect.ts'
-import { parseDocument } from 'yaml'
+import { isScalar, parseDocument, Scalar } from 'yaml'
 import { isSkillName, normalizeOutputPath } from '../paths.ts'
 import { checkProjectSkill } from './project.ts'
 import { err, ok } from '../result.ts'
@@ -15,6 +15,12 @@ const packageSkillLineLimit = 500
 /** `generate-package-skill`: "Write at most eight reference files." */
 const packageSkillReferenceLimit = 8
 
+/**
+ * Skill loaders and viewers parse frontmatter with different YAML parsers.
+ * A plain one-line description without these characters reads the same in all of them.
+ */
+const riskyDescription = /["`%]/
+
 /**
  * The Skill that produced the output decides which of its written rules apply.
  * A project Skill also carries the project paths its pointers must resolve to.
@@ -125,6 +131,9 @@ export const validateGeneratedSkill = (
     issues.push('Frontmatter name is invalid.')
   if (typeof frontmatter.description !== 'string' || frontmatter.description.trim().length === 0 || frontmatter.description.length > 1024)
     issues.push('Frontmatter description must contain 1 to 1024 characters.')
+  const description = document.get('description', true)
+  if (typeof frontmatter.description === 'string' && (!isScalar(description) || description.type !== Scalar.PLAIN || riskyDescription.test(frontmatter.description)))
+    issues.push('Frontmatter description must be one plain line without double quotes, backticks, or %. Name symptoms in plain words.')
   issues.push(...structureIssues(source, files, contract))
 
   return issues.length === 0 ? ok(undefined) : invalid(issues)
diff --git a/packages/harness/test/e2e/harness.test.ts b/packages/harness/test/e2e/harness.test.ts
index 74bb0374..d8d724a8 100644
--- a/packages/harness/test/e2e/harness.test.ts
+++ b/packages/harness/test/e2e/harness.test.ts
@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, readFile, symlink, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { createSkillHarness } from '../../src/index.ts'
@@ -237,6 +237,8 @@ describe('createSkillHarness', () => {
       async onPrompt({ workDir }) {
         const outputDir = join(workDir, 'skilld-output/example-project')
         await mkdir(outputDir, { recursive: true })
+        // Every repair turn links the file again.
+        await rm(join(outputDir, 'SKILL.md'), { force: true })
         await symlink(outside, join(outputDir, 'SKILL.md'))
       },
     })
diff --git a/packages/harness/test/e2e/output-checks.test.ts b/packages/harness/test/e2e/output-checks.test.ts
index 05da0acb..58e0e202 100644
--- a/packages/harness/test/e2e/output-checks.test.ts
+++ b/packages/harness/test/e2e/output-checks.test.ts
@@ -58,6 +58,49 @@ function linking(paths: ReadonlyArray<string>): string {
   return paths.map(path => `- [${path}](${path})`).join('\n')
 }
 
+const promptText = (prompt: unknown): string => typeof prompt === 'string' ? prompt : JSON.stringify(prompt)
+
+/** Runs a package Skill whose Agent writes `outputs[n]` on its nth turn, repeating the last one. */
+async function runTurns(outputs: ReadonlyArray<Output>) {
+  const packageDir = await mkdtemp(join(tmpdir(), 'skilld-checks-'))
+  await writeFile(join(packageDir, 'package.json'), '{"name":"example-package"}\n')
+  const destinationRoot = await mkdtemp(join(tmpdir(), 'skilld-checks-out-'))
+  let turn = 0
+  const fake = createFakeHarness({
+    async onPrompt({ sandbox, workDir }) {
+      const output = outputs[Math.min(turn++, outputs.length - 1)]!
+      for (const [path, content] of Object.entries(output))
+        await sandbox.writeTextFile({ path: join(workDir, 'skilld-output/example-package', path), content })
+    },
+  })
+  const result = await createSkillHarness({ harness: fake.harness, sandbox: createFakeSandboxProvider() }).run({
+    _tag: 'PackageSkill',
+    source: { _tag: 'LocalPackage', rootDir: packageDir, packageDir: '.' },
+    destination: { rootDir: destinationRoot, name: 'example-package' },
+  })
+  return { result, prompts: fake.capture.prompts.map(prompt => promptText(prompt.prompt)) }
+}
+
+describe('output check feedback', () => {
+  const invalid = { 'SKILL.md': `${frontmatter('example-package', 'license: MIT\n')}# Example\n` }
+  const valid = { 'SKILL.md': `${frontmatter('example-package')}# Example\n` }
+
+  it('sends failed checks back to the Agent in the same session and promotes the repaired Skill', async () => {
+    const { result, prompts } = await runTurns([invalid, valid])
+
+    expect(result).toMatchObject({ _tag: 'Ok', value: { _tag: 'GeneratedSkill' } })
+    expect(prompts).toHaveLength(2)
+    expect(prompts[1]).toContain('Frontmatter field is not supported: license')
+  })
+
+  it('returns the remaining issues after two repair turns', async () => {
+    const { result, prompts } = await runTurns([invalid])
+
+    expect(issues(result)).toContain('Frontmatter field is not supported: license')
+    expect(prompts).toHaveLength(3)
+  })
+})
+
 describe('generated Skill output checks', () => {
   it('promotes a package Skill that links eight references', async () => {
     const files = references(8)
@@ -115,6 +158,17 @@ describe('generated Skill output checks', () => {
     expect(result).toMatchObject({ _tag: 'Ok' })
   })
 
+  it.each([
+    ['Use it when a task reports "Nuxt not detected".', 'quotes'],
+    ['Use it when %siteName prints in the title.', 'percent'],
+    ['Use it when `useHead` throws.', 'backtick'],
+    ['>\n  Use it for head tags.', 'block'],
+  ])('rejects a description a Skill loader can misread (%s)', async (description) => {
+    const result = await runPackageSkill({ 'SKILL.md': `---\nname: example-package\ndescription: ${description}\n---\n\n# Example\n` })
+
+    expect(issues(result)).toContain('Frontmatter description must be one plain line without double quotes, backticks, or %. Name symptoms in plain words.')
+  })
+
   it('applies the frontmatter and link rules to a project Skill', async () => {
     const result = await runProjectSkill({
       'SKILL.md': `${frontmatter('example-project', 'license: MIT\n')}${projectSkillBody()}`,
diff --git a/packages/harness/test/e2e/run-events.test.ts b/packages/harness/test/e2e/run-events.test.ts
index 2f64c37a..ff3e73a7 100644
--- a/packages/harness/test/e2e/run-events.test.ts
+++ b/packages/harness/test/e2e/run-events.test.ts
@@ -159,7 +159,7 @@ describe('failed skill run report', () => {
     })
   })
 
-  it('reports usage and steps when the output check fails', async () => {
+  it('sums usage and steps across repair turns when the output check still fails', async () => {
     const { harness } = createFakeHarness({
       async onPrompt({ sandbox, workDir }) {
         await sandbox.writeTextFile({
@@ -179,7 +179,14 @@ describe('failed skill run report', () => {
     expect(result).toMatchObject({
       _tag: 'Err',
       error: { _tag: 'InvalidSkill' },
-      report: { steps: 1, usage: { outputTokens: 30 }, warnings: [] },
+      report: {
+        steps: 3,
+        usage: { outputTokens: 90 },
+        warnings: [
+          'Output checks failed; repair turn 1 of 2: Frontmatter name must match the Skill directory name.',
+          'Output checks failed; repair turn 2 of 2: Frontmatter name must match the Skill directory name.',
+        ],
+      },
     })
   })
 
diff --git a/skills/generate-package-skill/SKILL.md b/skills/generate-package-skill/SKILL.md
index c1d5ecda..b49a14df 100644
--- a/skills/generate-package-skill/SKILL.md
+++ b/skills/generate-package-skill/SKILL.md
@@ -45,6 +45,8 @@ Observed behaviour beats documentation.
 3. Run each example you include. Compare output with the claim: HTML, return values, type errors, build logs, exit codes, report files.
    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`.
@@ -102,6 +104,7 @@ 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.
+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
@@ -131,7 +134,7 @@ 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:
 
diff --git a/skills/generate-package-skill/assets/harness-request.md b/skills/generate-package-skill/assets/harness-request.md
index e900f17a..9f3d836a 100644
--- a/skills/generate-package-skill/assets/harness-request.md
+++ b/skills/generate-package-skill/assets/harness-request.md
@@ -13,3 +13,4 @@ List each documentation and behaviour mismatch in your final message.
 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.