@givolt/i3-composer-agent 2.0.0 → 2.1.1

package/scripts/lib/skill-lint.js

@@ -1,586 +0,0 @@
-'use strict';
-/**
- * skill-lint.js — the skill validation rules, as a shared library.
- *
- * This is the single source of truth for what makes a SKILL.md valid
- * (docs/skill-anatomy.md). The CLI in scripts/validate-skills.js is a thin
- * wrapper over it. Splitting the rules out of the CLI keeps them importable
- * and unit-testable without spawning a process or touching the filesystem.
- *
- * Checks (errors block CI):
- *   - SKILL.md exists in every skill directory
- *   - YAML frontmatter present with 'name' and 'description' fields
- *   - frontmatter 'name' matches the directory name
- *   - directory name is lowercase-hyphen-separated (skill-anatomy.md: Naming Conventions)
- *   - description does not exceed 1024 characters
- *   - description includes a 'when to use' trigger (skill-anatomy.md: Required)
- *   - required sections are present
- *   - a skill's subdirectories are non-empty (skill-anatomy.md: Supporting Files)
- *   - supporting .md filenames are lowercase-hyphen-separated
- *
- * Checks (warnings, do not block CI):
- *   - cross-skill references point to known skills
- *   - SKILL.md stays under the 500-line context budget
- */
-
-const fs   = require('fs');
-const path = require('path');
-
-// ─── Config ──────────────────────────────────────────────────────────────────
-
-const MAX_DESCRIPTION_LENGTH = 1024;
-
-// SKILL.md loads in full the moment an agent activates the skill, so its length
-// is paid for on every activation (docs/skill-anatomy.md -> Context Efficiency).
-// A warning, not an error: trimming a skill is an editorial call, and failing
-// CI on line count would block unrelated work on an over-budget skill.
-const MAX_SKILL_LINES = 500;
-
-// The only keys the Agent Skills specification allows at the top level of
-// SKILL.md frontmatter. Anything else — model hints, tool lists, turn limits,
-// host-specific switches — belongs under `metadata` or in a per-agent adapter
-// file (docs/advanced-per-agent-configuration.md). Hosts do not promise to
-// ignore unknown top-level keys, and a published skill carrying one can fail
-// packaging on a strict client, so this is an error rather than a warning.
-const SPEC_FRONTMATTER_KEYS = new Set([
-  'name',
-  'description',
-  'license',
-  'compatibility',
-  'metadata',
-  'allowed-tools',
-]);
-
-// A skill directory name must be lowercase-hyphen-separated
-// (docs/skill-anatomy.md → Naming Conventions).
-const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-
-// A description must state WHEN to use the skill, not just what it does
-// (docs/skill-anatomy.md → Required). Accept the canonical "Use when …"
-// plus the equivalent "Use before/after/during …" phrasings in use today.
-// Reject negated forms ("Do not use when …", "Don't use when …") — those
-// describe exclusions, not trigger conditions.
-const DESCRIPTION_TRIGGER        = /\buse (this )?when\b|\buse (before|after|during)\b/i;
-const DESCRIPTION_TRIGGER_NEGATE = /\b(do not|don't|never) use (this )?(when|before|after|during)\b/i;
-// Same pattern, global — used to strip *every* negated clause before checking
-// whether a positive trigger remains. Without /g only the first is removed, so
-// a description carrying two or more negated clauses and no positive one would
-// still match DESCRIPTION_TRIGGER on the leftovers and pass. Kept separate from
-// the non-global form above because a /g regex carries lastIndex across .test().
-const DESCRIPTION_TRIGGER_NEGATE_ALL = new RegExp(DESCRIPTION_TRIGGER_NEGATE.source, 'gi');
-
-// Sections every standard SKILL.md must contain.
-// Each entry is an array of acceptable heading strings — the first
-// match wins, so you can list canonical + legacy aliases.
-const REQUIRED_SECTIONS = [
-  ['## Overview'],
-  ['## When to Use'],
-  ['## Common Rationalizations'],
-  ['## Red Flags'],
-  ['## Verification'],
-];
-
-// Skills that are intentionally exempt from section checks.
-// Exemptions live HERE, not in skill frontmatter, so contributors
-// cannot bypass the validator by editing their own skill file.
-// Every entry must have a documented reason.
-const SECTION_EXEMPT_SKILLS = {
-  'i3-using-agent-skills': 'Branded alias of the reviewed upstream meta-skill.',
-  'i3-idea-refine': 'Branded alias of the reviewed upstream legacy structure.',
-  'using-agent-skills': 'Meta-skill — orchestrates other skills; When-to-Use and Verification are not applicable to a routing document.',
-  'idea-refine':        'Legacy structure predating skill-anatomy.md — uses How-It-Works/Usage/Anti-patterns instead of standard headings. Tracked for conformance in https://github.com/addyosmani/agent-skills/issues',
-};
-
-// Regex patterns that indicate an explicit cross-skill reference.
-// Only these patterns trigger the dead-reference warning — generic
-// backtick strings in code blocks are intentionally excluded.
-const SKILL_REF_PATTERNS = [
-  /\buse the `([a-z][a-z0-9-]+[a-z0-9])` skill/g,
-  /\bfollow the `([a-z][a-z0-9-]+[a-z0-9])` skill/g,
-  /\binvoke the `([a-z][a-z0-9-]+[a-z0-9])` skill/g,
-  /\bcontinue with `([a-z][a-z0-9-]+[a-z0-9])`/g,
-  /\buse `([a-z][a-z0-9-]+[a-z0-9])` skill/g,
-  /`([a-z][a-z0-9-]+[a-z0-9])` skill\b/g,
-  /`([a-z][a-z0-9-]+[a-z0-9])` persona\b/g,
-  /\bsee `([a-z][a-z0-9-]+[a-z0-9])`/g,
-  /──→ ([a-z][a-z0-9-]+[a-z0-9])\b/g,          // ASCII diagram arrows
-  /→ `([a-z][a-z0-9-]+[a-z0-9])`/g,
-];
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-/**
- * Strip fenced code blocks from markdown content so that headings, references,
- * and trigger phrases inside examples or templates are not matched by lint rules.
- *
- * Scans line by line and follows the CommonMark fence rules rather than a single
- * whole-document regex, which only recognised a column-zero backtick fence closed
- * by a run of exactly the same length (#437). The forms that regex let through:
- *
- *   - tilde fences (`~~~`)
- *   - fences indented by one to three spaces (common inside list items)
- *   - a closing fence longer than its opener
- *
- * A fence closes only on a run of the *same* marker at least as long as the
- * opener; a shorter run, or the other marker, is content. An unterminated fence
- * runs to end of file, so everything after it is treated as fenced and any
- * required section below it is reported missing rather than silently accepted.
- *
- * Stripped lines are replaced with empty lines so line numbers are preserved
- * for callers that report positions.
- */
-function stripFencedCodeBlocks(content) {
-  const out = [];
-  let open = null; // { marker: '`' | '~', length: number } while inside a fence
-
-  for (const line of content.split(/\r?\n/)) {
-    if (open) {
-      const close = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/);
-      if (close && close[1][0] === open.marker && close[1].length >= open.length) {
-        open = null;
-      }
-      out.push('');
-      continue;
-    }
-
-    const start = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
-    // CommonMark: the info string of a backtick fence may not contain backticks,
-    // so a line like ````js``` is inline code` is prose, not an opener.
-    if (start && !(start[1][0] === '`' && start[2].includes('`'))) {
-      open = { marker: start[1][0], length: start[1].length };
-      out.push('');
-      continue;
-    }
-
-    out.push(line);
-  }
-
-  return out.join('\n');
-}
-
-/**
- * List the top-level keys in the frontmatter block, in file order. Only
- * column-zero `key:` lines count: indented lines are children of the key
- * above them (e.g. fields under `metadata`), and `- item` lines are list
- * entries. Returns [] when there is no frontmatter block.
- */
-function topLevelFrontmatterKeys(content) {
-  const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/);
-  if (!match) return [];
-  const keys = [];
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = line.match(/^([A-Za-z0-9_-]+)\s*:/);
-    if (m) keys.push(m[1]);
-  }
-  return keys;
-}
-
-/**
- * Parse YAML-style frontmatter from the top of a markdown file.
- * Returns a key→value object, or null if no frontmatter block found.
- * Values are stripped of surrounding quotes.
- */
-function parseFrontmatter(content) {
-  const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/);
-  if (!match) return null;
-
-  const result = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const colonIdx = line.indexOf(':');
-    if (colonIdx === -1) continue;
-    const key   = line.slice(0, colonIdx).trim();
-    const value = line.slice(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '');
-    if (key) result[key] = value;
-  }
-  return result;
-}
-
-/**
- * Report frontmatter that this file's own parser accepts but a real YAML
- * parser rejects.
- *
- * `parseFrontmatter` above splits each line on its first colon. That is enough
- * to read `name` and `description`, and it is deliberately forgiving — but it
- * means a SKILL.md whose frontmatter is not valid YAML passes every check here.
- * The hosts that consume these skills do not share that forgiveness: Cursor
- * parses the frontmatter as YAML when a skill is attached to a message, and a
- * parse failure there fails the whole request with a generic server error and
- * takes the rest of the chat's context with it (#494).
- *
- * So the repo could ship frontmatter that breaks a host while CI stayed green.
- * That was verified once by hand, against all 25 skills, in the #494 thread;
- * this makes it a check instead of a memory.
- *
- * Scope is deliberately narrow — the shapes a strict parser rejects and the
- * split-on-first-colon parser does not, each confirmed by measurement against
- * both PyYAML and ruby's psych rather than read off the spec:
- *
- *   description: Use this: when X    unquoted value with a colon-space: YAML
- *                                    reads a nested mapping and errors
- *   \tkey: value                      tab indentation: invalid YAML whitespace
- *   description: "unterminated       an unclosed quote
- *   description: `skill` does X      a value opening with a YAML indicator
- *                                    (` @ % * ,) or a one-line | / > header
- *
- * It is not a YAML implementation. This repo has no package.json and therefore
- * no parser to depend on, so the check stays a small set of rules aimed at the
- * classes actually observed to break a host. No current frontmatter uses block
- * scalars or multi-line values, and the check assumes that stays true; add a
- * rule here rather than loosening one if it changes.
- */
-function frontmatterYamlErrors(content) {
-  const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/);
-  if (!match) return [];
-
-  const errors = [];
-  const lines = match[1].split(/\r?\n/);
-  lines.forEach((line, i) => {
-    const lineNo = i + 2; // the opening `---` is line 1
-    if (!line.trim()) return;
-
-    if (/^[ ]*\t/.test(line)) {
-      errors.push(
-        `Frontmatter line ${lineNo} indents with a tab — YAML forbids tabs in indentation, ` +
-        `so a host that parses this frontmatter rejects the whole file`
-      );
-      return;
-    }
-
-    const colonIdx = line.indexOf(':');
-    if (colonIdx === -1) return;
-    const value = line.slice(colonIdx + 1).trim();
-    if (!value) return;
-
-    const quote = value[0] === '"' || value[0] === "'" ? value[0] : null;
-    if (quote) {
-      // An opening quote must close. `endsWith` is enough here because a
-      // trailing comment after a quoted scalar does not appear in this repo.
-      if (value.length < 2 || !value.endsWith(quote)) {
-        errors.push(
-          `Frontmatter line ${lineNo} opens a ${quote === '"' ? 'double' : 'single'} quote that never closes — ` +
-          `a host parsing this frontmatter as YAML rejects the whole file`
-        );
-      }
-      return;
-    }
-
-    // Unquoted scalar. A plain YAML scalar may not BEGIN with certain indicator
-    // characters. The set below was measured against a real parser rather than
-    // read off the spec, both with and without a following space, and only the
-    // characters invalid in *both* forms with no legitimate single-line use are
-    // rejected — a guard that flags valid frontmatter gets switched off.
-    //
-    // Deliberately not rejected, because each parses cleanly: `:` or `-` when NOT
-    // followed by a space (`:platform`, `-hyphenated`), `#`, `&anchor`, and
-    // `[`/`{`, which begin valid flow collections — `[a, b]` and `{a: b}` both
-    // parse, so flagging the opening bracket would reject valid frontmatter.
-    //
-    // An earlier version of this comment claimed a leading `,`, `]` or `}` also
-    // parsed cleanly. Measured against PyYAML and psych, all three are rejected;
-    // `,` is flagged below. `]` and `}` are left out only because no frontmatter
-    // has ever started with them — say so and they can be added.
-    //
-    // The backtick is the one that bites this repo: descriptions routinely name
-    // other skills, and "`other-skill` designs things" is a natural way to start.
-    if (/^[`@%*,]/.test(value)) {
-      errors.push(
-        `Frontmatter line ${lineNo} starts an unquoted value with '${value[0]}' — YAML reserves ` +
-        `that character and cannot begin a plain scalar with it, so a host parsing this ` +
-        `frontmatter rejects the whole file; wrap the value in quotes`
-      );
-      return;
-    }
-    // `|` and `>` open a block scalar only when nothing follows them on the line.
-    // `|` with indented lines under it is valid and stays allowed; `|foo` is not
-    // a block scalar, it is a plain scalar starting with an indicator, and both
-    // parsers reject it.
-    if (/^[|>]\S/.test(value)) {
-      errors.push(
-        `Frontmatter line ${lineNo} starts an unquoted value with '${value[0]}' followed by text — ` +
-        `YAML reads that as a block scalar header, which may not carry content on its own line, ` +
-        `so a host parsing this frontmatter rejects the whole file; wrap the value in quotes`
-      );
-      return;
-    }
-    if (/^[-?&](\s|$)/.test(value)) {
-      errors.push(
-        `Frontmatter line ${lineNo} starts an unquoted value with '${value[0]} ' — YAML reads ` +
-        `that as an indicator rather than text and rejects the file; wrap the value in quotes`
-      );
-      return;
-    }
-
-    // A colon followed by a space (or ending the line) makes YAML read a nested
-    // mapping where a plain string was meant.
-    if (/:(\s|$)/.test(value)) {
-      errors.push(
-        `Frontmatter line ${lineNo} has an unquoted value containing ': ' — YAML reads that as a ` +
-        `nested mapping and rejects the file; wrap the value in quotes`
-      );
-    }
-  });
-
-  return errors;
-}
-
-/**
- * Collect all explicit skill cross-references from content.
- * Only matches against the SKILL_REF_PATTERNS list to avoid
- * false-positives from inline code snippets.
- */
-function extractSkillReferences(content) {
-  const refs = new Set();
-  for (const pattern of SKILL_REF_PATTERNS) {
-    // Reset lastIndex for global regexes
-    pattern.lastIndex = 0;
-    let m;
-    while ((m = pattern.exec(content)) !== null) {
-      refs.add(m[1]);
-    }
-  }
-  return refs;
-}
-
-// ─── Linter ──────────────────────────────────────────────────────────────────
-
-/**
- * Lint already-read SKILL.md content. Pure: no filesystem access, so the rules
- * can be exercised against crafted fixtures in a unit test.
- * Returns { errors, warnings, exempt }.
- */
-function lintSkillContent(dirName, content, knownSkills) {
-  const errors   = [];
-  const warnings = [];
-  let   exempt   = false;
-
-  // ── Frontmatter ──────────────────────────────────────────────────────────
-  const fm = parseFrontmatter(content);
-  if (!fm) {
-    errors.push('Missing or malformed YAML frontmatter (expected --- block at top of file)');
-    return { errors, warnings, exempt };
-  }
-
-  // The parser above is forgiving by design; the hosts that read this
-  // frontmatter are not (#494).
-  errors.push(...frontmatterYamlErrors(content));
-
-  // Only the specification's keys may sit at the top level. Vendor and
-  // runtime fields go under `metadata` or in a per-agent adapter file.
-  for (const key of topLevelFrontmatterKeys(content)) {
-    if (!SPEC_FRONTMATTER_KEYS.has(key)) {
-      errors.push(
-        `Frontmatter key '${key}' is not an Agent Skills spec field — top level allows only ` +
-        `${[...SPEC_FRONTMATTER_KEYS].join(', ')}; put vendor or runtime fields under 'metadata' ` +
-        `or in a per-agent adapter file (docs/advanced-per-agent-configuration.md)`
-      );
-    }
-  }
-
-  if (!fm.name) {
-    errors.push("Frontmatter missing required field: 'name'");
-  } else if (fm.name !== dirName) {
-    errors.push(`Frontmatter name '${fm.name}' does not match directory name '${dirName}'`);
-  }
-
-  if (!KEBAB_CASE.test(dirName)) {
-    errors.push(`Directory name '${dirName}' is not lowercase-hyphen-separated (skill-anatomy.md: Naming Conventions)`);
-  }
-
-  if (!fm.description) {
-    errors.push("Frontmatter missing required field: 'description'");
-  } else {
-    if (fm.description.length > MAX_DESCRIPTION_LENGTH) {
-      errors.push(
-        `Description is ${fm.description.length} chars — exceeds the ${MAX_DESCRIPTION_LENGTH}-char limit` +
-        ` (agents inject this into the system prompt)`
-      );
-    }
-    const hasTrigger       = DESCRIPTION_TRIGGER.test(fm.description);
-    const onlyNegated      = hasTrigger && DESCRIPTION_TRIGGER_NEGATE.test(fm.description)
-      && !fm.description.replace(DESCRIPTION_TRIGGER_NEGATE_ALL, '').match(DESCRIPTION_TRIGGER);
-    if (!hasTrigger || onlyNegated) {
-      errors.push(
-        `Description has no 'when to use' trigger — add a "Use when …" clause ` +
-        `(skill-anatomy.md: Required — the description must say both what the skill does and when to use it)`
-      );
-    }
-  }
-
-  // ── Exemption guard ──────────────────────────────────────────────────────
-  // Exemptions are validator-owned (SECTION_EXEMPT_SKILLS above).
-  // If a skill's frontmatter tries to declare its own exemption, fail loud —
-  // that's a sign someone is trying to bypass the validator.
-  if (fm.type === 'meta' || fm.exempt === 'sections') {
-    if (!Object.hasOwn(SECTION_EXEMPT_SKILLS, dirName)) {
-      errors.push(
-        `Frontmatter declares 'type: meta' or 'exempt: sections' but '${dirName}' is not in ` +
-        `the validator's SECTION_EXEMPT_SKILLS allowlist. ` +
-        `Add an entry to scripts/lib/skill-lint.js with a documented reason.`
-      );
-    }
-  }
-
-  // ── Required sections ────────────────────────────────────────────────────
-  // `Object.hasOwn`, not `in`: `in` walks the prototype chain, so a skill
-  // directory named `constructor` — which passes the kebab-case check — would
-  // otherwise resolve to Object.prototype.constructor and be silently exempt
-  // from every required-section check.
-  exempt = Object.hasOwn(SECTION_EXEMPT_SKILLS, dirName);
-
-  if (!exempt) {
-    // Strip fenced code blocks so headings inside examples/templates don't
-    // satisfy the check, and match headings at the start of a line so
-    // `### Verification` inside a block doesn't satisfy `## Verification`.
-    const proseContent = stripFencedCodeBlocks(content);
-    for (const aliases of REQUIRED_SECTIONS) {
-      const found = aliases.some(heading => {
-        const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        return new RegExp(`^${escaped}\\s*$`, 'm').test(proseContent);
-      });
-      if (!found) {
-        errors.push(`Missing required section: ${aliases[0]}`);
-      }
-    }
-  }
-
-  // A named workflow that advertises numbered steps must document each step
-  // before the next level-two section. Otherwise the summary promises a
-  // process stage that the skill never teaches agents how to perform.
-  const workflowSections = content.matchAll(
-    /^## The [^\n]+ Workflow\s*\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/gm
-  );
-  for (const match of workflowSections) {
-    const section = match[1];
-    const declared = [...section.matchAll(/^\s*(\d+)\.\s+[A-Z][A-Z -]*\s+→/gm)];
-    if (declared.length < 2) continue;
-
-    const documented = new Set(
-      [...section.matchAll(/^### Step\s+(\d+):/gm)].map(step => step[1])
-    );
-    for (const step of declared) {
-      if (!documented.has(step[1])) {
-        errors.push(`Workflow declares Step ${step[1]} but has no matching process section`);
-      }
-    }
-  }
-
-  // ── Context budget ───────────────────────────────────────────────────────
-  // Counted as newlines so the number matches what `wc -l` reports, which is
-  // how a contributor would check this by hand.
-  const lineCount = (content.match(/\n/g) || []).length;
-  if (lineCount > MAX_SKILL_LINES) {
-    warnings.push(
-      `SKILL.md is ${lineCount} lines, over the ${MAX_SKILL_LINES}-line context budget ` +
-      `(skill-anatomy.md: Context Efficiency) — move detail into a supporting file`,
-    );
-  }
-
-  // ── Cross-skill references ───────────────────────────────────────────────
-  const refs = extractSkillReferences(content);
-  for (const ref of refs) {
-    if (!knownSkills.has(ref)) {
-      warnings.push(`Dead cross-reference: \`${ref}\` is not a known skill`);
-    }
-  }
-
-  return { errors, warnings, exempt };
-}
-
-/** True when dir contains no regular file at any depth. */
-function isEffectivelyEmpty(dir) {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory()) {
-      if (!isEffectivelyEmpty(path.join(dir, entry.name))) return false;
-    } else {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Lint the files that travel with a skill, as opposed to the contents of
- * SKILL.md. These rules need the filesystem, so they live here rather than in
- * the pure content linter. Returns an array of error strings.
- *
- * Enforced (docs/skill-anatomy.md):
- *   - Supporting Files: "do not create an empty `scripts/` directory just to
- *     mirror other skills". Generalized to any subdirectory — an empty
- *     `references/` is noise for the same reason.
- *   - Naming Conventions: "Supporting files: lowercase-hyphen-separated.md".
- *     Scoped to .md, which is what that line covers; `scripts/` helpers carry
- *     their own conventions under Script Requirements.
- */
-function lintSkillLayout(skillDir) {
-  const errors = [];
-
-  const walk = (dir, relBase) => {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-
-      if (entry.isDirectory()) {
-        if (isEffectivelyEmpty(abs)) {
-          errors.push(
-            `Empty directory \`${rel}/\` — remove it rather than mirroring another skill's layout ` +
-            `(skill-anatomy.md: Supporting Files)`,
-          );
-        } else {
-          walk(abs, rel);
-        }
-        continue;
-      }
-
-      if (rel === 'SKILL.md' || !entry.name.endsWith('.md')) continue;
-      if (!KEBAB_CASE.test(entry.name.slice(0, -'.md'.length))) {
-        errors.push(
-          `Supporting file \`${rel}\` is not lowercase-hyphen-separated ` +
-          `(skill-anatomy.md: Naming Conventions)`,
-        );
-      }
-    }
-  };
-
-  walk(skillDir, '');
-  return errors;
-}
-
-/**
- * Lint a skill by directory name: reads its SKILL.md, then delegates to
- * lintSkillContent. This is the thin filesystem wrapper the CLI uses.
- * Returns { errors, warnings, exempt }.
- */
-function lintSkill(dirName, skillsDir, knownSkills) {
-  const skillDir  = path.join(skillsDir, dirName);
-  const skillPath = path.join(skillDir, 'SKILL.md');
-
-  if (!fs.existsSync(skillPath)) {
-    return { errors: ['Missing SKILL.md'], warnings: [], exempt: false };
-  }
-
-  let content;
-  try {
-    content = fs.readFileSync(skillPath, 'utf8');
-  } catch (err) {
-    return { errors: [`Unreadable SKILL.md: ${err.message}`], warnings: [], exempt: false };
-  }
-
-  const result = lintSkillContent(dirName, content, knownSkills);
-  result.errors.push(...lintSkillLayout(skillDir));
-  return result;
-}
-
-// Export only functions. The policy collections (REQUIRED_SECTIONS,
-// SECTION_EXEMPT_SKILLS, SKILL_REF_PATTERNS, and the regexes) stay private so a
-// test or future consumer cannot mutate shared state and change lint results for
-// the rest of the process. Exercise the rules through these functions.
-module.exports = {
-  stripFencedCodeBlocks,
-  parseFrontmatter,
-  topLevelFrontmatterKeys,
-  frontmatterYamlErrors,
-  extractSkillReferences,
-  lintSkillContent,
-  lintSkillLayout,
-  lintSkill,
-};