Package agent skill across harnesses

Author: noeltock

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## Unreleased
+
+### Changed
+
+- **The bundled agent skill is now canonical and cross-harness.** Its source lives at
+  `skills/block-runner/`, where the directory matches the frontmatter name, with the detailed
+  guide under `references/`. `skill --install` copies the complete bundle to both
+  `.agents/skills/block-runner/` and `.claude/skills/block-runner/` by default; `--scope`,
+  `--target`, and `--dir` cover user-wide, single-harness, and arbitrary roots.
+- **Skill installation is inspectable and guarded.** `--dry-run` resolves destinations without
+  writes, repeat installs are idempotent, managed files carry hashes, local changes are refused
+  unless `--force` is explicit, and installed runtime commands are pinned to the installing
+  package version while the explicit update command stays on `@latest`.
+
+### Fixed
+
+- The skill metadata now states its Node/shell/registry requirements, and the guide no longer
+  describes an uncached `npx` run as fully offline or treats frontend-scraped HTML as supported
+  authored input.
+- Pre-manifest 0.7.x installations now fail closed on their first upgrade. After review, rerun
+  with `--force`; the obsolete root-level `GUIDE.md` is preserved rather than deleted.
+- Skill installs reject symlinked discovery roots, and default dual-target installs preflight
+  ordinary write permissions across both destinations before changing either one.
+
 ## 0.7.1
 
 ### Fixed

README.md

@@ -29,7 +29,7 @@ WordPress, editable in any editor with nothing proprietary to keep installed.
 npm install block-runner          # requires Node 20+
 ```
 
-Then just ask your coding agent (Claude Code, Codex):
+Then just ask your coding agent:
 
 > Use block-runner to convert this hero into a native Gutenberg block.
 
@@ -49,20 +49,35 @@ block-runner convert hero.html --out hero.blocks.html
 Every run is checked against headless Gutenberg, so what comes back is guaranteed
 editor-valid, or Block Runner tells you exactly what wasn't and points at the line.
 
-## Using this from an AI agent?
+## Using Block Runner from an AI agent
 
 If you are the one deciding the structure, don't write HTML and convert it. Describe the
 structure as an intent tree and pipe it to `block-runner assemble` — deterministic code builds
 the markup, so it cannot come out invalid.
 
-There is a guide covering that path, the block mappings, and how to check markup before saving
-it to a site:
+Block Runner ships a canonical skill in the open Agent Skills layout. Install it into the
+current project (ask the user before writing files):
 
 ```sh
-npx block-runner skill              # print the guide — nothing is installed or written
-npx block-runner skill --install    # install it as a skill (ask the user first)
+npx block-runner skill --install
 ```
 
+That installs the same skill to the cross-agent `.agents/skills/block-runner` location and
+Claude Code's `.claude/skills/block-runner` compatibility location. Project scope is the
+default so the instructions can travel with a repository. Use user scope or one target when
+that is what you want:
+
+```sh
+npx block-runner skill --install --scope user
+npx block-runner skill --install --target agents
+npx block-runner skill --install --target claude
+```
+
+For a harness with another skills directory, use `--dir <skills-directory>`. With no skill
+system, `npx block-runner skill` prints the complete harness-neutral guide to stdout and writes
+nothing. Project discovery is the most portable choice; user-wide discovery paths still vary
+between harnesses, so use `--dir` when a client documents a different global root.
+
 ## Benchmark
 
 ![Fidelity benchmark: raw Claude and Codex writing block markup themselves score 35 to 73, while Block Runner with the same models scores 93 to 99, across simple and complex blocks](https://cdn.jsdelivr.net/gh/humanmade/block-runner@main/assets/benchmark.png)
@@ -178,6 +193,25 @@ All commands:
 | `--wp-user <user>` | WordPress username for `rest` resolution. |
 | `--wp-app-password-env <name>` | Env var holding a WordPress application password. |
 
+`skill --install` adds installation flags:
+
+| Flag | Description |
+| --- | --- |
+| `--scope project\|user` | Install for the current project (default) or the current user. |
+| `--target all\|agents\|claude` | Install both discovery copies (default), only `.agents/skills`, or only `.claude/skills`. |
+| `--dir <path>` | Install under one explicit skills directory; cannot be combined with `--scope` or `--target`. |
+| `--dry-run` | Show resolved destinations without writing files. |
+| `--force` | Replace locally changed or unmanaged files at canonical bundle paths. |
+
+Installed instructions pin runtime commands to the package version that installed them, while
+their explicit update command stays on `@latest`. Re-run
+`npx block-runner@latest skill --install` to update them. Existing local edits are refused
+unless `--force` is explicit.
+
+An installation made by 0.7.x predates the managed manifest, so the first upgrade is
+deliberately refused as unmanaged. Review that copy, rerun once with `--force`, and remove the
+preserved root-level `GUIDE.md` after confirming the new `references/GUIDE.md` copy.
+
 ### Exit codes
 
 - `0`: clean

package.json

@@ -48,7 +48,7 @@
     "LICENSE",
     "CHANGELOG.md",
     "examples",
-    "skill",
+    "skills",
     "scripts/prune-wp-vips.mjs"
   ],
   "engines": {

scripts/check-private-refs.mjs

@@ -21,6 +21,15 @@ const output = execFileSync(
 );
 
 const files = packFilePaths(output);
+const requiredPaths = [
+  'skills/block-runner/SKILL.md',
+  'skills/block-runner/references/GUIDE.md',
+];
+const missingPaths = requiredPaths.filter((file) => !files.includes(file));
+if (missingPaths.length > 0) {
+  console.error(`Required public files are missing from the package:\n${missingPaths.join('\n')}`);
+  process.exit(1);
+}
 const forbiddenPaths = [/^md\//, /^AGENTS\.md$/, /^CLAUDE\.md$/, /^\.env/];
 const forbiddenTerms = [
   'dogfood',

scripts/engines/engine-skill.ts

@@ -1,7 +1,7 @@
 /**
  * Engine Skill — measures the SHIPPED guide, not the tuned prompt.
  *
- * Engine C sends the tuner-owned `INTENT_PROMPT`. This engine sends `skill/GUIDE.md` — the
+ * Engine C sends the tuner-owned `INTENT_PROMPT`. This engine sends the canonical skill guide — the
  * text we actually publish — plus the minimal task framing a real agent would supply. Same
  * `realize()` on the other side, so the only variable is the instructions.
  *
@@ -20,7 +20,7 @@ import type { ConvertOptions, BlockRunnerReport } from '../../src/types.js';
 import { realize } from './intent.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-const GUIDE = readFileSync(path.join(ROOT, 'skill', 'GUIDE.md'), 'utf8');
+const GUIDE = readFileSync(path.join(ROOT, 'skills', 'block-runner', 'references', 'GUIDE.md'), 'utf8');
 
 // The framing an agent supplies around the guide when it has been handed a design to convert.
 // Deliberately thin: any lifting here is lifting the guide is not doing.

skill/SKILL.md skills/block-runner/SKILL.mdskill/SKILL.md renamed to skills/block-runner/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: block-runner
 description: >-
-  Produce, convert, and validate WordPress Gutenberg block markup so it lands in the editor as
-  real, native, editable blocks instead of one frozen Custom HTML blob. Use whenever you are
-  building WordPress page content or sections (hero, pricing table, FAQ, CTA band, feature
-  grid), converting HTML or a design-tool export into blocks, or checking block markup before
-  saving it to a site. Also use before any WordPress write that carries block markup. Runs
-  offline and deterministically via `npx block-runner` — no API key. NOT for WordPress admin
-  tasks, plugin or theme code, or non-WordPress HTML.
+  Turn WordPress content or authored design HTML into valid, native, editable Gutenberg blocks.
+  Use when creating WordPress page content or sections, converting authored HTML or a design-tool
+  export into block markup, validating or repairing Gutenberg markup, or before writing block
+  markup to WordPress. Do not use for general WordPress administration, plugin or theme code,
+  frontend-scraped HTML, or non-WordPress HTML.
+license: GPL-2.0-or-later
+compatibility: Requires Node.js 20+ and shell access. An uncached npx run requires npm registry access.
 ---
 
 # Block Runner
 
-Read `GUIDE.md` next to this file — it is the full contract and is the same guide shipped in
-the npm package.
+Read `references/GUIDE.md` for the full contract. It is the same guide shipped in the npm
+package.
 
 ## The short version
 
@@ -23,7 +23,7 @@ Three paths. Pick by what you have:
   describing which blocks and how they nest) and pipe it to
   `npx -y block-runner@latest assemble - --json`. Deterministic code builds the markup, so it
   cannot come out invalid. This is the best path and the one to reach for by default.
-- **You have someone else's HTML** → `npx -y block-runner@latest convert - --json`. The only
+- **You have authored source HTML** → `npx -y block-runner@latest convert - --json`. The only
   path that carries CSS; use it when the styling matters (`--styling relaxed` is the default).
 - **You have block markup to check** → `validate` → `fix` → `validate`. Never save markup that
   is still invalid after `fix`.
@@ -33,7 +33,8 @@ Three paths. Pick by what you have:
 - **Finish the job — the markup has to land somewhere.** Write it where the user asked; or
   offer to write it through a WordPress connection if one is available; or show it to them
   with the paste instruction (**Options ⋮ → Code editor**, or `Ctrl+Shift+Alt+M` — pasting
-  into the *visual* editor produces a mess). Never leave it in a temp file. See `GUIDE.md` §5.
+  into the *visual* editor produces a mess). Never leave it in a temp file. See
+  `references/GUIDE.md` §5.
 - **Always pass `--json`.** Without it the report items are dropped and you will miss
   fallbacks, warnings, and source locations.
 - **Never hand-write `<!-- wp:... -->` markup.** That is how invalid output happens. Describe
@@ -47,4 +48,4 @@ Three paths. Pick by what you have:
   say so — never block the user on it.
 
 Block structure rules, the full node schema, per-section mappings, token and media resolution,
-exit codes, and failure posture are all in `GUIDE.md`.
+exit codes, and failure posture are all in `references/GUIDE.md`.

skill/GUIDE.md skills/block-runner/references/GUIDE.mdskill/GUIDE.md renamed to skills/block-runner/references/GUIDE.md

@@ -6,8 +6,9 @@ gets it into the editor as real, native, editable blocks instead of one frozen H
 This guide is harness-neutral. Read it and act on it directly, or install it as a skill —
 see the end.
 
-Everything runs offline and deterministically. Block Runner never calls a model and never
-needs an API key. **You** are the model in this pipeline.
+Conversion, assembly, and validation run locally and deterministically. Block Runner never
+calls a model and never needs an API key. An uncached `npx` invocation still needs npm registry
+access to fetch the package. **You** are the model in this pipeline.
 
 ---
 
@@ -16,7 +17,7 @@ needs an API key. **You** are the model in this pipeline.
 | You have | Use | Why |
 |---|---|---|
 | A design in your head, or HTML you are about to write | **`assemble`** | You describe the structure; Block Runner builds valid blocks from it. Best structural results. |
-| Someone else's HTML — a design tool export, a paste, scraped markup | **`convert`** | Rule-based translation of existing markup, and the only path that carries CSS. |
+| Authored source HTML — a design tool export, source file, or paste | **`convert`** | Rule-based translation of existing markup, and the only path that carries CSS. Do not use frontend-scraped render output. |
 | Block markup you already produced, before saving it to WordPress | **`validate`** → **`fix`** → **`validate`** | Proves the editor will accept it. |
 
 The single most common mistake is reaching for `convert` when you were about to author the
@@ -275,12 +276,28 @@ harmless. Read results from stdout or `--json`. Users who run this often can
 
 ## 8. Installing this as a skill
 
-If your harness supports skills, this guide can be installed as one:
+If your harness supports skills, install the canonical skill into the current project:
 
 ```bash
 npx -y block-runner@latest skill --install
 ```
 
+That writes the same skill to the cross-agent `.agents/skills/block-runner` location and to
+Claude Code's `.claude/skills/block-runner` compatibility location. Narrow it when needed:
+
+```bash
+npx -y block-runner@latest skill --install --target agents
+npx -y block-runner@latest skill --install --target claude
+npx -y block-runner@latest skill --install --scope user
+npx -y block-runner@latest skill --install --dir .another-agent/skills
+npx -y block-runner@latest skill --install --dry-run
+```
+
+Project discovery is the most portable choice. User-wide discovery paths still vary between
+harnesses, so use `--dir` when a client documents a different global skills root.
+The installer pins runtime examples to its own package version so the guide and CLI contract
+stay aligned. To update later, rerun `npx -y block-runner@latest skill --install`.
+
 **Ask the user first.** This writes files into their project, which is their call, not yours.
 If they decline, or their harness has no skill system, nothing is lost — reading this guide is
 the same information. `npx -y block-runner@latest skill` prints it without installing anything.

src/cli.ts

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { Command, CommanderError } from 'commander';
+import { Command, CommanderError, Option } from 'commander';
 import fg from 'fast-glob';
 import { canonicalize } from './gate/canonicalize.js';
 import { validate } from './gate/validate.js';
 import { convert } from './convert/assemble.js';
 import { realize } from './intent/index.js';
 import { loadConfig } from './config/load.js';
 import { collectSiteContext } from './context/run.js';
+import { installCanonicalSkill, readCanonicalSkillGuide, SkillScope, SkillTarget } from './skill.js';
 import { BlockRunnerReport, CommonOptions, HeadlessBootError } from './types.js';
 
 const { version: packageVersion } = createRequire(import.meta.url)('../package.json') as {
@@ -38,6 +40,10 @@ interface ContextCliOptions {
 interface SkillCliOptions {
   install?: boolean;
   dir?: string;
+  scope?: SkillScope;
+  target?: SkillTarget;
+  dryRun?: boolean;
+  force?: boolean;
 }
 
 const program = new Command();
@@ -205,26 +211,38 @@ program
   .command('skill')
   .description('Print or install the agent guide.')
   .option('--install', 'install the agent skill files')
-  .option('--dir <path>', 'install root (default: .claude/skills)')
+  .addOption(new Option('--scope <scope>', 'installation scope (default: project)').choices(['project', 'user']))
+  .addOption(new Option('--target <target>', 'skill discovery target (default: all)').choices(['all', 'agents', 'claude']))
+  .option('--dir <path>', 'install under an explicit skills directory')
+  .option('--dry-run', 'show destinations without writing files')
+  .option('--force', 'replace locally changed or unmanaged skill files')
   .action(async (options: SkillCliOptions) => {
     if (!options.install) {
-      process.stdout.write(await readSkillSource('GUIDE.md'));
+      if (options.dir || options.scope || options.target || options.dryRun || options.force) {
+        program.error('error: --dir, --scope, --target, --dry-run, and --force require --install');
+      }
+      process.stdout.write(await readCanonicalSkillGuide());
       return;
     }
 
-    const skill = await readSkillSource('SKILL.md');
-    const guide = await readSkillSource('GUIDE.md');
-    const destination = path.resolve(options.dir ?? '.claude/skills', 'block-runner');
-    await mkdir(destination, { recursive: true });
-
-    for (const [filename, content] of [
-      ['SKILL.md', skill],
-      ['GUIDE.md', guide],
-    ] as const) {
-      const target = path.join(destination, filename);
-      const status = existsSync(target) ? 'updated' : 'installed';
-      await writeFile(target, content, 'utf8');
-      console.log(`${status} ${target}`);
+    const results = await installCanonicalSkill({
+      cwd: process.cwd(),
+      home: process.env.HOME || homedir(),
+      packageVersion,
+      directory: options.dir,
+      scope: options.scope,
+      target: options.target,
+      dryRun: options.dryRun,
+      force: options.force,
+    });
+    for (const result of results) {
+      const status = result.dryRun && result.status !== 'unchanged'
+        ? `would ${result.status === 'installed' ? 'install' : 'update'}`
+        : result.status;
+      console.log(`${status} ${result.destination}`);
+      for (const warning of result.warnings) {
+        console.error(`warning: ${warning}`);
+      }
     }
   });
 
@@ -400,17 +418,6 @@ function emitHint(report: BlockRunnerReport): void {
   }
 }
 
-async function readSkillSource(filename: 'SKILL.md' | 'GUIDE.md'): Promise<string> {
-  const source = filename === 'GUIDE.md'
-    ? new URL('../skill/GUIDE.md', import.meta.url)
-    : new URL('../skill/SKILL.md', import.meta.url);
-  try {
-    return await readFile(source, 'utf8');
-  } catch {
-    throw new Error(`skill source file is missing: ${source.pathname}`);
-  }
-}
-
 function formatTextReport(report: BlockRunnerReport): string {
   const status = report.ok ? 'ok' : 'problems found';
   const lines = [