@jaybeeuu/agent-cortex 1.43.0 → 2.1.0

package/extensions/agent-modes/discover.ts

@@ -18,9 +18,9 @@ import type { ThemeColor } from "@earendil-works/pi-coding-agent";
  *      and symlinked installs).
  *
  * Flat `agents/*.agent.md` files are parsed as a fallback for agents that have
- * no composable directory (they are generated output for Copilot, so they may
- * exist for any agent). A composable directory always wins over its flat
- * counterpart.
+ * no composable directory (a staged pi package ships flat renders, and a
+ * hand-written agent may be a single flat file). A composable directory always
+ * wins over its flat counterpart.
  */
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -40,7 +40,7 @@ export interface AgentDef {
   prompt: string;
 }
 
-export type HarnessId = "copilot" | "claude" | "pi";
+export type HarnessId = "claude" | "pi";
 
 export interface PathSpec {
   base: string;
@@ -431,8 +431,8 @@ function readFlatAgent(filePath: string, tokenMap: TokenMap | null): AgentDef |
  * Discover agents from the agents directory.
  *
  * Composable directories (`<name>/agent.md` + `<name>/pi/frontmatter.json`) are
- * the primary source. Flat `*.agent.md` files (generated output for Copilot) are
- * read only when no composable directory exists for that agent id. When
+ * the primary source. Flat `*.agent.md` files (a staged package's renders, or a
+ * hand-written agent) are read only when no composable directory exists for that agent id. When
  * `tokenMap` is omitted, token-map.json is loaded from the package root;
  * missing/unreadable maps fall back to the built-in copilot→pi translation.
  */

package/extensions/output-style/README.md

@@ -0,0 +1,58 @@
+# Output Style
+
+Appends the always-on reply shape to the PI system prompt once per user prompt.
+
+This is the second slice of `docs/ideas/improve-pi-system-prompt.md`: the first
+(`agent-guardrails`) stops wasted work; this one stops the answer getting buried in
+it. The extension injects a stable block via the `before_agent_start` hook — which
+fires once per user prompt, before the agent loop — so the rules apply to every
+turn of the run without rewriting Pi's default prompt.
+
+## Rules
+
+- **Lead with the action** — the first line is the answer, command, path, or next
+  action; multi-step work is numbered; the reply ends with one next step.
+- **Keep the prose short** — no preamble, no recap, no closing offer; five items
+  per list at most; one topic per reply.
+- **Write Simplified Technical English (ASD-STE100)** — active voice, 20-word
+  sentences for instructions and 25-word sentences for description, verb over
+  noun, one word one meaning, literal words, no marketing adjectives, articles
+  kept.
+- **Restate the context** — never cite a bead, ticket, phase, or stage by ID alone;
+  say what it is in plain words first, and restate state after a gap or topic
+  switch.
+
+The rules shape the reply, never the work. When a rule would delete the answer,
+the task wins.
+
+## Structure
+
+```
+output-style/
+├── README.md              # This file
+├── index.ts               # Extension entry point — appends on before_agent_start
+├── output-style.ts        # Loads the block + appendOutputStyle composition
+├── output-style.md        # The block text (single source, also shipped to Claude)
+├── output-style.test.ts   # Composition tests
+├── package.json
+└── tsconfig.json
+```
+
+## Testing
+
+```bash
+cd extensions/output-style
+node --test --import tsx/esm output-style.test.ts
+```
+
+## Design notes
+
+- The block is a stable constant appended after any chained system-prompt changes,
+  so the prompt-cache prefix is preserved.
+- `appendOutputStyle` is idempotent — a prompt that already carries the marker is
+  returned unchanged, so a duplicate extension load cannot double the rules.
+- Separate from `agent-guardrails` because it is a different failure: guardrails
+  govern *whether* work continues, this governs *how the result is reported*.
+- The prose lives in `output-style.md`, not in the TypeScript, because there is a
+  second consumer: `agent-cortex install claude` wraps that file in the managed
+  `~/.claude/CLAUDE.md` section. One file, two harnesses, no drift.

package/extensions/output-style/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Output Style Extension
+ *
+ * Appends the always-on reply shape to the PI system prompt on every turn: lead
+ * with the action, write in Simplified Technical English (ASD-STE100), restate the
+ * context the reader cannot remember (the second slice of
+ * docs/ideas/improve-pi-system-prompt.md).
+ *
+ * The block is stable text appended after any chained system-prompt changes, so it
+ * keeps the prompt-cache prefix intact while remaining authoritative for the model.
+ * See output-style.ts for the rules and appendOutputStyle for composition.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendOutputStyle } from "./output-style.ts";
+
+export { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+export default function outputStyleExtension(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", (event) => {
+    return { systemPrompt: appendOutputStyle(event.systemPrompt) };
+  });
+}

package/extensions/output-style/output-style.md

@@ -0,0 +1,43 @@
+## Output style (agent-cortex)
+
+How every reply is written. These rules shape the reply, never the work: do all
+the analysis and tool calls the task needs, then report the result this way. If a
+rule would delete the answer itself, the task wins; the shape stays.
+
+### Lead with the action
+
+- The first line is the answer, the command, the path, or the next action. Not
+  context, not a plan, not "Let me…".
+- Number multi-step work. One bounded action per step.
+- End with one concrete next step. Omit it when the work is finished.
+
+### Keep the prose short
+
+- No preamble ("Great question", "I'll now…"), no recap of work just completed,
+  no closing offer ("Let me know if…", "Hope this helps").
+- Five items maximum per list. Rank them; group related items.
+- One topic per reply. Name a tangent in one line at the end, then stop.
+
+### Write Simplified Technical English (ASD-STE100)
+
+- Active voice. Imperative for instructions.
+- Sentence limit: 20 words for instructions, 25 for descriptive text. One
+  instruction per sentence.
+- Use the verb, not the noun: "check the file", not "perform a check of the file".
+- One word, one meaning: pick the term for a thing, then reuse it.
+- Literal words only. No idioms, metaphors, or figures of speech ("circle back",
+  "under the hood", "ballpark").
+- No marketing adjectives or filler ("seamless", "robust", "comprehensive").
+- Keep articles and subjects. Do not compress into fragments that lose meaning.
+- Give times in concrete units ("about 10 minutes"), never "a bit of work".
+
+### Restate the context, never assume it
+
+The reader cannot hold earlier turns in working memory.
+
+- Never name a bead, ticket, phase, or pipeline stage by ID or number alone. Say
+  what it is in plain words first — "the login fix, verify step (bd-142)" — and
+  give the ID at most once.
+- After a gap, a topic switch, or a long tool run, restate in one line: what is
+  done, what is next.
+- Mark progress concretely: "Step 2 of 4 done: schema updated."

package/extensions/output-style/output-style.test.ts

@@ -0,0 +1,50 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { OUTPUT_STYLE, OUTPUT_STYLE_MARKER, appendOutputStyle } from "./output-style.ts";
+
+// ─── appendOutputStyle ────────────────────────────────────────────────────────
+
+describe("appendOutputStyle", () => {
+  it("appends the output-style block after the base prompt", () => {
+    const result = appendOutputStyle("You are a helpful agent.");
+
+    assert.ok(result.startsWith("You are a helpful agent."));
+    assert.ok(result.includes(OUTPUT_STYLE));
+  });
+
+  it("preserves a chained base prompt from earlier handlers", () => {
+    const base = "Base prompt.\n\n---\nAgent mode instructions.";
+    const result = appendOutputStyle(base);
+
+    assert.ok(result.startsWith(base));
+  });
+
+  it("trims trailing whitespace before appending", () => {
+    const result = appendOutputStyle("Base prompt.\n\n");
+
+    assert.equal(result, `Base prompt.\n\n${OUTPUT_STYLE}`);
+  });
+
+  it("keeps a block appended by another extension", () => {
+    const withGuardrails = "Base prompt.\n\n## Operating discipline (agent-cortex)\n\nRules.\n";
+    const result = appendOutputStyle(withGuardrails);
+
+    assert.ok(result.includes("## Operating discipline (agent-cortex)"));
+    assert.ok(result.endsWith(OUTPUT_STYLE));
+  });
+
+  it("is idempotent when applied twice", () => {
+    const once = appendOutputStyle("Base prompt.");
+    const twice = appendOutputStyle(once);
+
+    assert.equal(twice, once);
+    assert.equal(twice.split(OUTPUT_STYLE_MARKER).length - 1, 1);
+  });
+
+  it("returns the prompt unchanged when the output style is already present", () => {
+    const existing = `Base prompt.\n\n${OUTPUT_STYLE}`;
+
+    assert.equal(appendOutputStyle(existing), existing);
+  });
+});

package/extensions/output-style/output-style.ts

@@ -0,0 +1,32 @@
+/**
+ * Output style for the PI system prompt.
+ *
+ * The second slice of docs/ideas/improve-pi-system-prompt.md: the reply shape, not
+ * the task discipline. Three concerns, in order — lead with the action, write in
+ * Simplified Technical English, restate the context the reader cannot remember.
+ *
+ * The prose lives in output-style.md so one file feeds both harnesses: this
+ * extension appends it to the PI system prompt, and the Claude installer wraps it
+ * in a managed CLAUDE.md section. It is read once at load, so the appended text is
+ * stable across turns and keeps the prompt-cache prefix intact. The marker doubles
+ * as an idempotency guard: a chained prompt that already carries the block is
+ * returned unchanged.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const OUTPUT_STYLE_MARKER = "## Output style (agent-cortex)";
+
+export const OUTPUT_STYLE = readFileSync(new URL("./output-style.md", import.meta.url), "utf-8");
+
+/**
+ * Append the output-style block to a system prompt.
+ *
+ * The base prompt is preserved verbatim (minus trailing whitespace) so callers can
+ * chain this after other `before_agent_start` handlers. Idempotent: a prompt that
+ * already contains the marker is returned unchanged.
+ */
+export function appendOutputStyle(systemPrompt: string): string {
+  if (systemPrompt.includes(OUTPUT_STYLE_MARKER)) return systemPrompt;
+  return `${systemPrompt.trimEnd()}\n\n${OUTPUT_STYLE}`;
+}

package/extensions/output-style/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-cortex/output-style",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm output-style.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.1"
+  }
+}

package/extensions/output-style/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/extensions/subagent/README.md

@@ -111,8 +111,8 @@ fire-and-forget orchestration:
 - **`read_agent`** — fallback: read one specific agent's output once you know it has
   finished (or query its `STILL RUNNING` state directly).
 
-These mirror Copilot CLI's `task`/`read_agent` model; `wait_for_agents` adds the
-blocking wait that Copilot's poll loop does manually. Abort (Ctrl+C) propagates: a
+These mirror the `task`/`read_agent` model the skills are authored against;
+`wait_for_agents` adds the blocking wait that a `read_agent` poll loop does manually. Abort (Ctrl+C) propagates: a
 pending `wait_for_agents` returns immediately with whatever is known so far.
 
 ## Output Display

package/extensions/subagent/agents.ts

@@ -155,8 +155,7 @@ function isRenderedAgentsTree(agentsDir: string): boolean {
  * renders the flat pi agents into `<package>/agents`.
  *
  * A source checkout contributes nothing: its `agents/` tree is the composable
- * source (composed at runtime by the agent-modes extension) alongside flat
- * renders for other harnesses — Copilot's, whose tool names pi does not have.
+ * source, composed at runtime by the agent-modes extension.
  */
 export function resolveUserAgentDirs(packageRoot: string = PACKAGE_ROOT): string[] {
 	const dirs: string[] = [];

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
+const SUPPORTED_HARNESSES = ["claude", "pi"];
 
 // Options accepted by `install <harness>`. `--output`/`--dry-run` are shared by
 // the claude and pi installers; `--plugin-root` is pi-specific. Unknown or
@@ -87,11 +87,6 @@ Commands:
                                         registration cannot run (missing CLI,
                                         pre-v2 build); default warns and prints
                                         the manual registration commands
-                      Options (copilot):
-                        --output <dir>   Write the flat *.agent.md files to <dir>
-                                         (default: <package root>/agents — the dir
-                                         plugin.json "agents" scans)
-                        --dry-run        Print what would be generated without writing
                       Options (pi):
                         (no --output)         Materialise the pi package into
                                               ~/.agent-cortex/pi: package.json,
@@ -135,7 +130,10 @@ Commands:
 
 export function validateHarness(harness) {
   if (harness === null) {
-    return { ok: false, error: "Missing harness argument. Supported harnesses: copilot, claude, pi" };
+    return {
+      ok: false,
+      error: `Missing harness argument. Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}`,
+    };
   }
   if (!SUPPORTED_HARNESSES.includes(harness)) {
     return { ok: false, error: `Unknown harness "${harness}". Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.43.0",
+  "version": "2.1.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -35,16 +35,15 @@
   },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
-    "lint": "pnpm typecheck && pnpm check:sync",
+    "lint": "pnpm typecheck && pnpm check:sync && pnpm check:skills",
     "check:sync": "node scripts/check-no-sync.mjs",
+    "check:skills": "node scripts/check-skill-frontmatter.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:copilot",
+    "version-packages": "changeset version",
     "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "publish-noop": "echo 'No publish: the merged PR carries the no-publish label.'",
-    "release": "changeset publish",
-    "postinstall": "bash scripts/install-instructions.sh"
+    "release": "changeset publish"
   }
 }

package/scripts/check-skill-frontmatter.mjs

@@ -0,0 +1,21 @@
+// Repo convention: every SKILL.md frontmatter must parse and declare a name and
+// description, because PI silently drops a skill whose frontmatter throws. Runs
+// via `pnpm lint` (CI) and locally. Scans the repository root, so both skills/
+// and repo-local .agents/skills/ are covered.
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSkills } from "./lib/skill-frontmatter.mjs";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+const { checked, failures } = await checkSkills({ root: ROOT });
+
+if (failures.length > 0) {
+  console.error("✗ Invalid SKILL.md frontmatter — PI would silently drop these skills:");
+  for (const { file, errors } of failures) {
+    for (const error of errors) console.error(`  ${file}: ${error}`);
+  }
+  process.exit(1);
+}
+
+console.log(`✓ SKILL.md frontmatter valid (${checked} files)`);

package/scripts/lib/compose-agent.mjs

@@ -1,8 +1,8 @@
 // Shared composer: reads a composable agent directory (agents/<name>/) and emits
-// the harness-specific agent content defined by agents/README.md. The Copilot
-// generator (scripts/build-copilot-agents.mjs) and the Claude install-time generator
-// (bin/installers/claude.mjs) compose from here, so the composable dirs are
-// the single source of truth and the flat/generated files stay in lockstep.
+// the harness-specific agent content defined by agents/README.md. The Claude and pi
+// install-time generators (bin/installers/claude.mjs, bin/installers/pi.mjs) compose
+// from here, so the composable dirs are the single source of truth and the generated
+// files stay in lockstep.
 //
 // Composition per the agents/README.md contract:
 //   1. {{SECTION:name}} is replaced with <dir>/<harness>/<name>.md content.
@@ -15,15 +15,15 @@
 // silently dropped section.
 //
 // Options (the pi installer passes `dropNullTools`, `pluginRoot` and
-// `resolveRelativePaths`; the copilot generator and claude installer use the strict defaults):
+// `resolveRelativePaths`; the claude installer uses the strict defaults):
 //   dropNullTools          replace null-mapped tool tokens with an empty string and
 //                          warn instead of throwing (pi's prose rule per the
 //                          token-map contract)
 //   pluginRoot             override the plugin_root used for resolved paths
 //                          (installers compute it from the actual install layout)
 //   resolveRelativePaths   non-keyed {{PATH:...}} args resolve to pluginRoot/arg
-//                          instead of staying verbatim (install time; the build
-//                          scripts leave them bare for Copilot CLI resolution)
+//                          instead of staying verbatim (install time; without it
+//                          they stay bare for runtime resolution)
 //   warn                   callback for drop/omit warnings (default: no-op; the
 //                          pi installer collects them into its result)
 //
@@ -61,7 +61,7 @@ function noop() {}
  *   the harness's section files before calling this.
  *
  * @param {string} content  Source text containing {{TOOL:...}}/{{PATH:...}} tokens
- * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness  Harness id: "claude" | "pi"
  * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
  * @param {object} options  { dropNullTools, pluginRoot, resolveRelativePaths, warn, context }
  * @returns {string}
@@ -99,7 +99,7 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  *
  * @param {string} root    Package root (contains agents/ and token-map.json)
  * @param {string} name    Agent directory name (e.g. "ralph", "plan")
- * @param {string} harness Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness Harness id: "claude" | "pi"
  * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
  */
 export async function composeAgent(root, name, harness, options = {}) {
@@ -218,7 +218,7 @@ function resolvePath(arg, harness, tokenMap, opts = {}) {
  *
  * @param {string[]} tools  Canonical tool names from a harness frontmatter.json
  * @param {object} tokenMap Parsed token-map.json (from loadTokenMap)
- * @param {string} harness  Harness id: "copilot" | "claude" | "pi"
+ * @param {string} harness  Harness id: "claude" | "pi"
  * @param {object} options  { warn }
  * @returns {string[]}
  */

package/scripts/lib/skill-frontmatter.mjs

@@ -0,0 +1,135 @@
+// SKILL.md frontmatter validation, shared by `pnpm lint` (via
+// scripts/check-skill-frontmatter.mjs) and its tests.
+//
+// PI reads a skill's frontmatter with `parse` from the `yaml` package and
+// silently drops the skill when that parse throws — only a warning diagnostic
+// is emitted. A skill whose frontmatter is broken therefore disappears from the
+// prompt with no visible failure. This module makes that failure loud: every
+// SKILL.md must parse, declare a non-empty `name` and `description`, and keep
+// the description within PI's 1024-character limit.
+//
+// Frontmatter extraction mirrors PI's parseFrontmatter (dist/utils/frontmatter.js), so a
+// SKILL.md that PI drops — frontmatter that will not parse, or no description — fails here
+// too. The check is stricter than PI in two places PI only warns about: `name` must be a
+// non-empty frontmatter field (PI falls back to the directory name), and a description over
+// 1024 characters is an error.
+//
+// Known gaps, each verified against PI's loader and left unhandled on purpose:
+// - A symlinked SKILL.md is skipped: `entry.isFile()` is false for a symlink, while PI
+//   stats through the link and loads it. No symlinked SKILL.md exists in this repo.
+// - Duplicate `name` values across skill roots are not detected: validation is per-file
+//   with no name index, while PI drops the loser of a name collision.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { parse } from "yaml";
+
+/** PI's maximum description length — a longer description is rejected. */
+export const MAX_DESCRIPTION_LENGTH = 1024;
+
+const SKILL_FILE = "SKILL.md";
+const SKIPPED_DIRS = new Set([".git", "node_modules"]);
+
+/**
+ * Return the YAML text between the leading `---` delimiters, or null when the
+ * document has no frontmatter block. Mirrors PI's extraction step, including
+ * newline normalisation and BOM stripping.
+ */
+function extractYaml(content) {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return null;
+
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return null;
+
+  return normalized.slice(4, endIndex);
+}
+
+/** True when `value` is a string with at least one non-whitespace character. */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Validate one SKILL.md document.
+ *
+ * @param {string} content - Raw SKILL.md contents.
+ * @returns {string[]} Human-readable problems; empty when the frontmatter is valid.
+ */
+export function validateSkillFrontmatter(content) {
+  const yamlText = extractYaml(content);
+  if (yamlText === null) {
+    return ["frontmatter block is missing (expected '---' delimiters)"];
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = parse(yamlText);
+  } catch (error) {
+    const message = error instanceof Error ? error.message.split("\n")[0] : "unknown parse error";
+    return [`frontmatter is not valid YAML: ${message}`];
+  }
+
+  if (frontmatter === null || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    return ["frontmatter is not a YAML mapping of name/description fields"];
+  }
+
+  const errors = [];
+  if (!isNonEmptyString(frontmatter.name)) {
+    errors.push("frontmatter is missing a non-empty name");
+  }
+  if (!isNonEmptyString(frontmatter.description)) {
+    errors.push("frontmatter is missing a non-empty description");
+  } else if (frontmatter.description.length > MAX_DESCRIPTION_LENGTH) {
+    errors.push(
+      `description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${frontmatter.description.length})`,
+    );
+  }
+
+  return errors;
+}
+
+/** Recursively collect every SKILL.md below `dir`, skipping vendored trees. */
+async function findSkillFiles(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      found.push(...(await findSkillFiles(full)));
+    } else if (entry.isFile() && entry.name === SKILL_FILE) {
+      found.push(full);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Validate every SKILL.md under `root`.
+ *
+ * @param {{ root: string }} options
+ * @returns {Promise<{ checked: number, failures: Array<{ file: string, errors: string[] }> }>}
+ *   `checked` counts the SKILL.md files examined; `failures` holds one entry per
+ *   invalid file, with `file` relative to `root`.
+ */
+export async function checkSkills({ root }) {
+  const files = await findSkillFiles(root);
+  const failures = [];
+
+  for (const file of files) {
+    const content = await readFile(file, "utf-8");
+    const errors = validateSkillFrontmatter(content);
+    if (errors.length > 0) {
+      failures.push({ file: relative(root, file), errors });
+    }
+  }
+
+  return { checked: files.length, failures };
+}