@oharness/engine 0.2.0 → 0.3.0

package/skills/plugin-creator/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: plugin-creator
+description: Creating or updating native OHarness plugin bundles with skills, subagents, hooks, MCP servers, project or user installation, and manifest validation.
+---
+
+# Create an OHarness plugin
+
+Choose between two native OHarness formats. A declarative bundle packages
+Skills, Subagents, Hooks, and MCP servers without importing JavaScript. A
+Runtime Plugin is trusted executable code that can register tools, Runtime
+Skills, models, authentication, hooks, audit sinks, prompts, pages, and
+background lifecycle work.
+
+## Choose the installation scope
+
+- Default to `<project>/.oharness/plugins/<name>/` for a repository-specific
+  plugin.
+- For a local/global installation available to every project, use
+  `$OHARNESS_HOME/plugins/<name>/` when set,
+  `$XDG_CONFIG_HOME/oharness/plugins/<name>/` on configured Linux systems, or
+  otherwise `~/.oharness/plugins/<name>/`.
+- Respect an explicit directory. Inspect an existing plugin before editing it
+  and never overwrite unrelated files.
+
+Both the Web and CLI frontends use the same plugin discovery in `Harness`, so a
+user-installed plugin is available to either frontend on its next Harness
+startup. Project and configured plugin directories override earlier plugins
+with the same name.
+
+Runtime Plugins are different: project configuration cannot activate executable
+modules. They must be supplied by the embedding application or enabled in the
+user `plugins.json` runtime-plugin list. Changes take effect on the next Harness
+startup.
+
+## Native bundle format
+
+Create only the parts the requested plugin needs:
+
+```text
+my-plugin/
+  oharness.plugin.json
+  skills/example/SKILL.md
+  agents/reviewer.md
+  scripts/audit.sh
+```
+
+The manifest needs only `name`. Supported optional fields are `version`,
+`description`, `mcpServers`, `hooks`, and inline `subagents`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Release and review workflows",
+  "mcpServers": {
+    "github": { "type": "http", "url": "https://example.com/mcp" }
+  },
+  "hooks": {
+    "PreToolUse": [{ "matcher": "mcp__github__*", "command": "./scripts/audit.sh" }]
+  }
+}
+```
+
+Skills under `skills/` and Markdown agents under `agents/` are discovered
+automatically and do not need manifest entries. A plugin can alternatively be
+added through `plugins.dirs` in configuration. OHarness can consume compatible
+Claude Code plugin bundles, but create the native `oharness.plugin.json` format
+unless the user explicitly requests cross-product compatibility.
+
+For a deterministic skeleton, run:
+
+```bash
+node <skill-base>/scripts/create-plugin.mjs <name> [--description "<text>"] [--version 1.0.0] [--with skills,agents,scripts] [--project <directory> | --user]
+```
+
+Resolve `<skill-base>` from the base directory shown when this skill loads; do
+not assume the current working directory is the built-in skill directory.
+The command refuses to replace an existing manifest unless `--force` is given.
+Use that flag only after inspecting the target and intentionally replacing it.
+Populate requested hooks and MCP declarations after scaffolding; do not invent
+commands, endpoints, credentials, or permissions.
+
+## Runtime Plugin mode
+
+When the request needs executable in-process behavior, add `--runtime`:
+
+```bash
+node <skill-base>/scripts/create-plugin.mjs <name> --runtime [--description "<text>"] [--version 1.0.0] [--project <directory> | --user]
+node <skill-base>/scripts/validate-runtime-plugin.mjs <path-to-runtime-plugin>
+```
+
+Implement only the requested capabilities through `setup(ctx)`. Register all
+contributions during setup, keep mutable state per Harness instance, honor
+`ctx.signal`, register cleanup immediately with `ctx.onDispose`, and make
+`ctx.onStart` return after starting background work rather than awaiting an
+infinite loop. Runtime Skill contributions use
+`ctx.skills.register({ name, description, body, directory? })`; the optional
+directory must be absolute.
+
+When installation is requested, add an entry with the generated id and absolute
+module path to the user `plugins.json` `runtimePlugins` list. Never enable
+executable code from project configuration, and do not change user configuration
+unless installation or enablement was explicitly requested.
+
+Plugin hooks and stdio MCP servers execute local commands. Treat the bundle as
+code, keep secrets as environment placeholders, and call out those executable
+parts when handing the plugin back.
+
+## Validate and activate
+
+Run:
+
+```bash
+node <skill-base>/scripts/validate-plugin.mjs <path-to-plugin>
+```
+
+Verify every referenced script or skill exists and test deterministic helpers.
+Plugin discovery happens when `Harness` starts, so restart the local CLI/Web
+process or begin a new session after installing a new bundle. Use `/plugins` to
+confirm the effective plugin and `/mcp` to inspect contributed MCP connections.

package/skills/plugin-creator/scripts/create-plugin.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+function fail(message) {
+  console.error(`plugin-creator: ${message}`);
+  process.exit(1);
+}
+
+function userRoot() {
+  if (process.env.OHARNESS_HOME) return path.resolve(process.env.OHARNESS_HOME);
+  if (process.platform === "linux" && process.env.XDG_CONFIG_HOME) return path.join(process.env.XDG_CONFIG_HOME, "oharness");
+  return path.join(homedir(), ".oharness");
+}
+
+function normalize(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63).replace(/-+$/g, "");
+}
+
+const args = process.argv.slice(2);
+const rawName = args.shift();
+if (!rawName) fail("usage: create-plugin.mjs <name> [--runtime] [--description <text>] [--version <value>] [--with a,b] [--project <dir> | --user] [--force]");
+
+let description;
+let version;
+let project = process.cwd();
+let useUser = false;
+let projectSpecified = false;
+let runtime = false;
+let force = false;
+let companions = [];
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "--description") description = args[++i];
+  else if (arg === "--version") version = args[++i];
+  else if (arg === "--project") { project = path.resolve(args[++i] ?? fail("--project needs a directory")); projectSpecified = true; }
+  else if (arg === "--user") useUser = true;
+  else if (arg === "--runtime") runtime = true;
+  else if (arg === "--with") companions = (args[++i] ?? "").split(",").filter(Boolean);
+  else if (arg === "--force") force = true;
+  else fail(`unknown option: ${arg}`);
+}
+if (useUser && projectSpecified) fail("choose either --user or --project");
+
+const name = normalize(rawName);
+if (!name) fail("name must contain a letter or digit");
+const allowed = new Set(["skills", "agents", "scripts"]);
+for (const companion of companions) if (!allowed.has(companion)) fail(`unsupported companion directory: ${companion}`);
+
+const parent = runtime
+  ? (useUser ? path.join(userRoot(), "runtime-plugins") : path.join(project, ".oharness", "runtime-plugins"))
+  : (useUser ? path.join(userRoot(), "plugins") : path.join(project, ".oharness", "plugins"));
+const directory = path.join(parent, name);
+const file = path.join(directory, runtime ? "index.mjs" : "oharness.plugin.json");
+if (!force) {
+  try {
+    await readFile(file, "utf8");
+    fail(`${file} already exists (pass --force only to replace it intentionally)`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+await mkdir(directory, { recursive: true });
+for (const companion of companions) await mkdir(path.join(directory, companion), { recursive: true });
+const manifest = {
+  name,
+  ...(version?.trim() ? { version: version.trim() } : {}),
+  ...(description?.trim() ? { description: description.trim() } : {}),
+};
+const output = runtime
+  ? `export default {\n  id: ${JSON.stringify(name)},\n  version: ${JSON.stringify(version?.trim() || "1.0.0")},\n  apiVersion: 1,\n  ${description?.trim() ? `description: ${JSON.stringify(description.trim())},\n  ` : ""}parseConfig(raw) {\n    if (raw !== undefined) throw new Error("This plugin takes no configuration");\n    return {};\n  },\n  setup(_ctx) {\n    // Register requested runtime capabilities here before returning.\n  },\n};\n`
+  : `${JSON.stringify(manifest, null, 2)}\n`;
+await writeFile(file, output, "utf8");
+console.log(file);

package/skills/plugin-creator/scripts/validate-plugin.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+
+const input = process.argv[2];
+if (!input) {
+  console.error("usage: validate-plugin.mjs <plugin-directory-or-oharness.plugin.json>");
+  process.exit(1);
+}
+
+const file = path.basename(input) === "oharness.plugin.json" ? path.resolve(input) : path.resolve(input, "oharness.plugin.json");
+const directory = path.dirname(file);
+const errors = [];
+let manifest;
+try {
+  manifest = JSON.parse(await readFile(file, "utf8"));
+} catch (error) {
+  errors.push(`cannot parse ${file}: ${error.message}`);
+}
+
+if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) errors.push("manifest must be a JSON object");
+const name = manifest?.name;
+if (typeof name !== "string" || !name.trim()) errors.push("manifest requires a non-empty name");
+if (typeof name === "string" && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) errors.push("name must be lowercase hyphen-case");
+if (typeof name === "string" && name.length >= 64) errors.push("name must be shorter than 64 characters");
+if (typeof name === "string" && path.basename(directory) !== name) errors.push("directory name must match manifest name");
+if (manifest?.mcpServers !== undefined && (!manifest.mcpServers || typeof manifest.mcpServers !== "object" || Array.isArray(manifest.mcpServers))) errors.push("mcpServers must be an object");
+if (manifest?.hooks !== undefined && (!manifest.hooks || typeof manifest.hooks !== "object" || Array.isArray(manifest.hooks))) errors.push("hooks must be an object");
+if (manifest?.subagents !== undefined && !Array.isArray(manifest.subagents)) errors.push("subagents must be an array");
+
+try {
+  const skills = path.join(directory, "skills");
+  for (const entry of await readdir(skills, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    try { await readFile(path.join(skills, entry.name, "SKILL.md"), "utf8"); }
+    catch { errors.push(`skills/${entry.name} is missing SKILL.md`); }
+  }
+} catch (error) {
+  if (error?.code !== "ENOENT") errors.push(`cannot inspect skills/: ${error.message}`);
+}
+
+if (errors.length) {
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log(`valid OHarness plugin: ${name}`);

package/skills/plugin-creator/scripts/validate-runtime-plugin.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const input = process.argv[2];
+if (!input) {
+  console.error("usage: validate-runtime-plugin.mjs <runtime-plugin-directory-or-module>");
+  process.exit(1);
+}
+
+const target = path.resolve(input);
+const file = (await stat(target)).isDirectory() ? path.join(target, "index.mjs") : target;
+const errors = [];
+let plugin;
+try { plugin = (await import(`${pathToFileURL(file).href}?validate=${Date.now()}`)).default; }
+catch (error) { errors.push(`cannot import ${file}: ${error.message}`); }
+if (!plugin || typeof plugin !== "object") errors.push("module must default-export a plugin object");
+if (typeof plugin?.id !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(plugin.id)) errors.push("plugin id is invalid");
+if (typeof plugin?.version !== "string" || !plugin.version) errors.push("plugin version is required");
+if (plugin?.apiVersion !== 1) errors.push("apiVersion must be 1");
+if (typeof plugin?.parseConfig !== "function") errors.push("parseConfig is required");
+if (typeof plugin?.setup !== "function") errors.push("setup is required");
+if (errors.length) {
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log(`valid OHarness runtime plugin: ${plugin.id}`);

package/skills/skill-authoring/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: skill-authoring
-description: Writing a SKILL.md — the frontmatter, where skills are discovered, and what makes a description one that actually gets matched.
+description: Explaining or reviewing the OHarness SKILL.md format, discovery order, and description matching. For creating or installing a skill, use skill-creator.
 ---
 
 # Writing a skill
 
+This is the format reference. Use the built-in `skill-creator` for a complete
+creation or installation workflow with scaffolding and validation.
+
 A skill is packaged instructions loaded on demand. Its **description** sits in
 the system prompt of every request; its **body** is only loaded when a task
 matches. That split is the whole point, and it drives every rule below.

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: skill-creator
+description: Creating or updating reusable OHarness skills, including project-local and user-wide installation, SKILL.md authoring, supporting files, and validation.
+---
+
+# Create an OHarness skill
+
+Create a small, discoverable skill that changes the agent's decisions for a
+specific workflow. Do not turn generic knowledge into a permanent system-prompt
+cost.
+
+## Choose the installation scope
+
+- Default to `<project>/.oharness/skills/<name>/` when the skill belongs to the
+  current repository or the user did not ask for a global installation.
+- Use the user skills directory when the user asks to install the skill locally,
+  globally, for every project, or for their account. This is
+  `$OHARNESS_HOME/skills/<name>/` when `OHARNESS_HOME` is set,
+  `$XDG_CONFIG_HOME/oharness/skills/<name>/` on Linux when XDG is configured,
+  and otherwise `~/.oharness/skills/<name>/`.
+- Respect an explicit destination. Do not write outside the configured
+  workspace roots without the required approval.
+
+Choose a persisted skill unless the user explicitly asks for a Runtime Skill.
+A Runtime Skill is trusted JavaScript registered in memory by a Runtime Plugin;
+it is useful when the instructions or lifecycle must be supplied
+programmatically. It is not a second executable escape hatch for ordinary
+markdown skills.
+
+Project skills override user and built-in skills with the same name. Inspect an
+existing destination before changing it and preserve unrelated resources.
+
+## Author the skill
+
+Use a lowercase hyphenated name under 64 characters. Every skill is a directory
+with one required `SKILL.md`:
+
+```markdown
+---
+name: deploy-service
+description: Deploying this service to Railway, including its preflight checks and rollback boundary.
+---
+
+# Deploy the service
+
+Run `scripts/preflight.sh` before changing the deployment.
+```
+
+The `description` is the only part visible before selection. Name the concrete
+request that should activate the skill; avoid descriptions such as "helper" or
+"utilities". The body should contain only non-obvious workflow, constraints,
+decision criteria, and references to supporting files.
+
+Add `scripts/`, `reference/`, or `assets/` only when the workflow needs them.
+Relative paths in the body resolve from the skill directory. Test executable
+helpers rather than assuming they work.
+
+For a deterministic initial file, run the bundled scaffold with the destination
+scope and complete instructions:
+
+```bash
+node <skill-base>/scripts/create-skill.mjs <name> --description "<selection description>" --instructions "<skill instructions>" [--project <directory> | --user]
+```
+
+Resolve `<skill-base>` from the base directory shown when this skill loads; do
+not assume the current working directory is the built-in skill directory.
+Pass `--resources scripts,reference,assets` only for directories that will be
+used. The command refuses to replace an existing skill unless `--force` is
+given; use that flag only after inspecting the target and intentionally
+replacing it.
+
+For a Runtime Skill, add `--runtime`. The scaffold produces an `index.mjs`
+whose Runtime Plugin calls `ctx.skills.register(...)`:
+
+```bash
+node <skill-base>/scripts/create-skill.mjs <name> --runtime --description "<selection description>" --instructions "<skill instructions>" [--project <directory> | --user]
+node <skill-base>/scripts/validate-runtime-skill.mjs <path-to-runtime-skill>
+```
+
+Runtime Skills are trusted executable modules. They must be enabled through the
+user `plugins.json` runtime-plugin list or supplied explicitly by an embedding
+application; project configuration cannot activate them. When activation is
+requested, use the generated plugin id `skill-<name>` and an absolute module
+path. Do not edit user plugin configuration unless the user asked to install or
+enable the Runtime Skill.
+
+## Validate and finish
+
+Run:
+
+```bash
+node <skill-base>/scripts/validate-skill.mjs <path-to-skill>
+```
+
+Also verify that the description matches realistic user wording, the body has
+no unfinished placeholders, and referenced files exist. Writing a
+`**/skills/**/SKILL.md` triggers OHarness skill discovery immediately, so the
+new skill can be used in the same Web or CLI session without restarting.

package/skills/skill-creator/scripts/create-skill.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+function fail(message) {
+  console.error(`skill-creator: ${message}`);
+  process.exit(1);
+}
+
+function userRoot() {
+  if (process.env.OHARNESS_HOME) return path.resolve(process.env.OHARNESS_HOME);
+  if (process.platform === "linux" && process.env.XDG_CONFIG_HOME) return path.join(process.env.XDG_CONFIG_HOME, "oharness");
+  return path.join(homedir(), ".oharness");
+}
+
+function normalize(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63).replace(/-+$/g, "");
+}
+
+const args = process.argv.slice(2);
+const rawName = args.shift();
+if (!rawName) fail("usage: create-skill.mjs <name> --description <text> --instructions <text> [--runtime] [--project <dir> | --user] [--resources a,b] [--force]");
+
+let description;
+let instructions;
+let project = process.cwd();
+let useUser = false;
+let projectSpecified = false;
+let runtime = false;
+let force = false;
+let resources = [];
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "--description") description = args[++i];
+  else if (arg === "--instructions") instructions = args[++i];
+  else if (arg === "--project") { project = path.resolve(args[++i] ?? fail("--project needs a directory")); projectSpecified = true; }
+  else if (arg === "--user") useUser = true;
+  else if (arg === "--runtime") runtime = true;
+  else if (arg === "--resources") resources = (args[++i] ?? "").split(",").filter(Boolean);
+  else if (arg === "--force") force = true;
+  else fail(`unknown option: ${arg}`);
+}
+if (!description?.trim()) fail("--description is required");
+if (!instructions?.trim()) fail("--instructions is required");
+if (useUser && projectSpecified) fail("choose either --user or --project");
+
+const name = normalize(rawName);
+if (!name) fail("name must contain a letter or digit");
+const allowedResources = new Set(["scripts", "reference", "assets"]);
+for (const resource of resources) if (!allowedResources.has(resource)) fail(`unsupported resource directory: ${resource}`);
+
+const parent = runtime
+  ? (useUser ? path.join(userRoot(), "runtime-skills") : path.join(project, ".oharness", "runtime-skills"))
+  : (useUser ? path.join(userRoot(), "skills") : path.join(project, ".oharness", "skills"));
+const directory = path.join(parent, name);
+const file = path.join(directory, runtime ? "index.mjs" : "SKILL.md");
+if (!force) {
+  try {
+    await readFile(file, "utf8");
+    fail(`${file} already exists (pass --force only to replace it intentionally)`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+await mkdir(directory, { recursive: true });
+for (const resource of resources) await mkdir(path.join(directory, resource), { recursive: true });
+const title = name.split("-").map((word) => word[0]?.toUpperCase() + word.slice(1)).join(" ");
+const cleanDescription = description.trim().replace(/\s+/g, " ");
+const body = runtime
+  ? `import { fileURLToPath } from "node:url";\n\nexport default {\n  id: ${JSON.stringify(`skill-${name}`)},\n  version: "1.0.0",\n  apiVersion: 1,\n  description: ${JSON.stringify(`Runtime skill: ${cleanDescription}`)},\n  parseConfig(raw) {\n    if (raw !== undefined) throw new Error("This runtime skill takes no configuration");\n    return {};\n  },\n  setup(ctx) {\n    ctx.skills.register({\n      name: ${JSON.stringify(name)},\n      description: ${JSON.stringify(cleanDescription)},\n      body: ${JSON.stringify(instructions.trim())},\n      directory: fileURLToPath(new URL(".", import.meta.url)),\n    });\n  },\n};\n`
+  : `---\nname: ${name}\ndescription: ${cleanDescription}\n---\n\n# ${title}\n\n${instructions.trim()}\n`;
+await writeFile(file, body, "utf8");
+console.log(file);

package/skills/skill-creator/scripts/validate-runtime-skill.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const input = process.argv[2];
+if (!input) {
+  console.error("usage: validate-runtime-skill.mjs <runtime-skill-directory-or-module>");
+  process.exit(1);
+}
+
+const file = (await stat(path.resolve(input))).isDirectory() ? path.resolve(input, "index.mjs") : path.resolve(input);
+const errors = [];
+let plugin;
+try { plugin = (await import(`${pathToFileURL(file).href}?validate=${Date.now()}`)).default; }
+catch (error) { errors.push(`cannot import ${file}: ${error.message}`); }
+if (!plugin || typeof plugin !== "object") errors.push("module must default-export a plugin object");
+if (plugin?.apiVersion !== 1 || typeof plugin?.id !== "string" || typeof plugin?.version !== "string") errors.push("runtime plugin requires id, version, and apiVersion: 1");
+if (typeof plugin?.parseConfig !== "function" || typeof plugin?.setup !== "function") errors.push("runtime plugin requires parseConfig and setup functions");
+
+let captured;
+if (!errors.length) {
+  try {
+    const config = await plugin.parseConfig(undefined);
+    await plugin.setup({ skills: { register(skill) { captured = skill; } } }, config);
+  } catch (error) { errors.push(`runtime skill setup failed: ${error.message}`); }
+}
+if (!captured) errors.push("plugin setup must register one runtime skill");
+if (captured && (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(captured.name) || !captured.description?.trim() || !captured.body?.trim())) errors.push("registered skill requires a valid name, description, and body");
+if (captured?.directory !== undefined && !path.isAbsolute(captured.directory)) errors.push("runtime skill directory must be absolute");
+
+if (errors.length) {
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log(`valid OHarness runtime skill: ${captured.name}`);

package/skills/skill-creator/scripts/validate-skill.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+const input = process.argv[2];
+if (!input) {
+  console.error("usage: validate-skill.mjs <skill-directory-or-SKILL.md>");
+  process.exit(1);
+}
+
+const file = path.basename(input) === "SKILL.md" ? path.resolve(input) : path.resolve(input, "SKILL.md");
+const directory = path.dirname(file);
+const errors = [];
+let raw = "";
+try {
+  if (!(await stat(file)).isFile()) errors.push("SKILL.md is not a file");
+  raw = await readFile(file, "utf8");
+} catch (error) {
+  errors.push(`cannot read ${file}: ${error.message}`);
+}
+
+const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(raw);
+if (!match) errors.push("SKILL.md must start with closed YAML frontmatter");
+const frontmatter = match?.[1] ?? "";
+const body = match?.[2]?.trim() ?? "";
+const name = /^name:\s*(.+)$/m.exec(frontmatter)?.[1]?.trim();
+const description = /^description:\s*(.+)$/m.exec(frontmatter)?.[1]?.trim();
+if (!name) errors.push("frontmatter requires name");
+if (!description) errors.push("frontmatter requires description");
+if (name && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) errors.push("name must be lowercase hyphen-case");
+if (name && name.length >= 64) errors.push("name must be shorter than 64 characters");
+if (name && path.basename(directory) !== name) errors.push("directory name must match frontmatter name");
+if (body.length < 40) errors.push("skill body is too short to provide useful instructions");
+if (/\bTODO\b|\[replace|<skill instructions>|<selection description>/i.test(raw)) errors.push("unfinished placeholder found");
+
+if (errors.length) {
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log(`valid OHarness skill: ${name}`);