skillgauntlet 1.0.0 → 1.1.0

package/lib/installed.js

@@ -0,0 +1,43 @@
+// Where a skill can already be installed. Claude Code, Codex and the shared .agents convention all
+// read a directory of skill folders, each with a SKILL.md inside.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Ordered: earlier roots win when the same skill name appears twice.
+const ROOTS = [
+  () => path.join(os.homedir(), '.agents', 'skills'),
+  () => path.join(process.cwd(), '.agents', 'skills'),
+  () => path.join(os.homedir(), '.claude', 'skills'),
+  () => path.join(process.cwd(), '.claude', 'skills'),
+  () => path.join(os.homedir(), '.codex', 'skills'),
+  () => path.join(process.cwd(), '.codex', 'skills'),
+];
+
+function skillName(dir) {
+  try {
+    const text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
+    const m = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+    const n = m && m[1].match(/^name\s*:\s*(.+)$/m);
+    if (n) return n[1].trim().replace(/^["']|["']$/g, '');
+  } catch { /* fall through */ }
+  return path.basename(dir);
+}
+
+export function installedSkills() {
+  const seen = new Map();
+  for (const rootFn of ROOTS) {
+    const root = rootFn();
+    let entries = [];
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue;
+      const dir = path.join(root, e.name);
+      if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue;
+      const name = skillName(dir);
+      if (seen.has(name)) continue;
+      seen.set(name, { name, dir, root });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/lib/queries.js

@@ -0,0 +1,37 @@
+// Question sets cost one model call to draft, so they are cached and reused while the skill is
+// unchanged. The fingerprint is the SKILL.md hash: edit the description and the cache goes stale,
+// which is exactly when fresh questions are needed.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function fingerprint(skillDir) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(path.join(skillDir, 'SKILL.md'))).digest('hex').slice(0, 16);
+  } catch { return null; }
+}
+
+export function cacheFileFor(skillDir, depth) {
+  return path.join(skillDir, '.skillgauntlet', `queries-${depth.perClause}x${depth.negatives}.json`);
+}
+
+export function readCachedQueries(file, want) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const same = j.perClause === want.perClause
+      && j.negatives === want.negatives
+      && j.skillFingerprint === want.skillFingerprint
+      && Array.isArray(j.queries) && j.queries.length > 0;
+    return same ? j : null;
+  } catch { return null; }
+}
+
+export function writeCachedQueries(file, payload) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+    return true;
+  } catch {
+    return false; // a read-only skill directory must not break the run
+  }
+}

package/lib/report.js

@@ -0,0 +1,145 @@
+// Rendering. Two artefacts: a machine-readable scorecard and a page a human can read.
+// Every sentence comes from the i18n table, so the report follows the language chosen in the CLI.
+import { t, lang } from './i18n.js';
+
+const ICON = { pass: '✓', warn: '!', fail: '✗', info: '·' };
+const pct = (x) => (x == null ? '—' : `${Math.round(x * 100)}%`);
+
+export function staticMarkdown(result) {
+  const s = result.stats;
+  const L = [];
+  L.push(`# ${result.skill}`);
+  L.push('');
+  L.push(`- ${t('report.path')}\`${result.path}\``);
+  L.push(`- ${t('report.skillMd', { chars: s.skillMdChars, tokens: s.skillMdTokens, desc: s.descriptionChars })}`);
+  L.push(`- ${t('report.package', { files: s.files, code: s.codeFiles, size: s.size })}`);
+  L.push(`- ${t('report.permissions', { tools: s.allowedTools || t('report.notDeclared') })}`);
+  L.push('');
+  L.push(`| ${t('report.groupHeader')} | ${t('report.verdictHeader')} | ${t('report.checkHeader')} |`);
+  L.push('|---|---|---|');
+  for (const g of result.groups) {
+    const bad = g.checks
+      .filter((c) => c.status === 'warn' || c.status === 'fail')
+      .map((c) => `${ICON[c.status]} ${t(c.titleKey)}`).join('; ');
+    L.push(`| ${g.id} ${t(g.titleKey)} | ${g.verdict} | ${bad || t('report.allPass')} |`);
+  }
+  L.push('');
+  L.push(t('report.legend'));
+  L.push('');
+  for (const g of result.groups) {
+    L.push(`## ${g.id} ${t(g.titleKey)}`);
+    L.push('');
+    for (const c of g.checks) {
+      L.push(`- ${ICON[c.status]} **${c.id} ${t(c.titleKey)}** — ${t(c.detailKey, c.detailVars)}`);
+      for (const e of c.evidence.slice(0, 3)) L.push(`  - \`L${e.line}\` ${e.match}`);
+    }
+    L.push('');
+  }
+  L.push(t('report.noComposite'));
+  return L.join('\n');
+}
+
+export function trialSection(trial) {
+  if (!trial) return '';
+  const L = ['', `## ${t('trial.title')}`, ''];
+  L.push(`- ${t('trial.modelLine', {
+    model: trial.modelResolved || trial.model,
+    backend: trial.backend,
+    host: trial.host || t('trial.hostUnknown'),
+    runs: trial.runs,
+    trials: trial.trials,
+  })}`);
+  L.push(`- ${t('trial.recall', { p: pct(trial.recall), lo: pct(trial.recallCi?.[0]), hi: pct(trial.recallCi?.[1]) })}`);
+  L.push(`- ${t('trial.fpr', { p: pct(trial.fpr), lo: pct(trial.fprCi?.[0]), hi: pct(trial.fprCi?.[1]) })}`);
+  if (trial.noToolRate != null) {
+    L.push(`- ${t('trial.noTool', { p: pct(trial.noToolRate) })}${trial.noToolRate >= 0.5 ? t('trial.noToolWarn') : ''}`);
+  }
+  L.push('');
+  L.push(`| ${t('trial.stateHeader')} | ${t('trial.queryHeader')} | ${t('trial.hitsHeader')} |`);
+  L.push('|---|---|---|');
+  for (const q of trial.questions) {
+    L.push(`| ${q.shouldTrigger ? t('trial.should') : t('trial.shouldNot')} | ${q.query.replace(/\|/g, '\\|')} | ${q.hits}/${q.n} |`);
+  }
+  return L.join('\n');
+}
+
+export function gainSection(gain) {
+  if (!gain) return '';
+  const L = ['', `## ${t('gain.title')}`, ''];
+  L.push(t('gain.intro'));
+  L.push(t('gain.local'));
+  L.push('');
+  L.push(`| ${t('gain.contractHeader')} | ${t('gain.withHeader')} | ${t('gain.withoutHeader')} | ${t('gain.dirHeader')} |`);
+  L.push('|---|---|---|---|');
+  for (const c of gain.contracts) {
+    const delta = c.with - c.without;
+    const dir = delta > 0.1 ? t('gain.up') : delta < -0.1 ? t('gain.down') : t('gain.same');
+    const desc = c.descI18n?.[lang()] || c.desc;
+    L.push(`| ${desc} | ${pct(c.with)} | ${pct(c.without)} | ${dir} |`);
+  }
+  if (gain.tasks?.length) {
+    L.push('');
+    L.push(`### ${t('gain.perTask')}`);
+    for (const task of gain.tasks) {
+      L.push('');
+      L.push(`**${task.id}**  ${task.prompt.replace(/\n/g, ' ').slice(0, 120)}`);
+      for (const [label, side] of [[t('gain.withSkill'), task.with], [t('gain.withoutSkill'), task.without]]) {
+        const files = side.added.length ? side.added.slice(0, 6).join(', ') : t('gain.noFiles');
+        const ok = side.checks.filter((c) => c.ok).length;
+        L.push(`- **${label}**: ${t('gain.side', { files, ok, n: side.checks.length })}`);
+      }
+    }
+  }
+  L.push('');
+  L.push(t('gain.footnote1'));
+  L.push(t('gain.footnote2'));
+  return L.join('\n');
+}
+
+export function probeSection(probe) {
+  if (!probe) return '';
+  const same = (b) => (b ? t('probeSame') : t('probeDiffer'));
+  const L = ['', `## ${t('probeTitle')}`, ''];
+  L.push(t('probeIntro'));
+  L.push('');
+  L.push(`| | ${t('probeAction')} | ${t('probeFiles')} |`);
+  L.push('|---|---|---|');
+  for (const [label, side] of [[t('probeWith'), probe.withSkill], [t('probeWithout'), probe.without]]) {
+    const action = side.firstAction ? `${side.firstAction.kind} — ${side.firstAction.detail}`.slice(0, 160) : '—';
+    L.push(`| ${label} | ${action} | ${side.createdFiles?.join(', ') || '—'} |`);
+  }
+  L.push('');
+  L.push(`- ${t('probeActionKind')}${t('report.colon')}${same(probe.actionKindIdentical)}`);
+  L.push(`- ${t('probeArtifacts')}${t('report.colon')}${same(probe.artifactsIdentical)}`);
+  L.push('');
+  L.push(`> ${t('probeNoVerdict')}`);
+  L.push(`> ${t('probeNoTrigger')}`);
+  return L.join('\n');
+}
+
+export function scorecard(result) {
+  return {
+    schema: 'skillgauntlet/scorecard/2',
+    skill: result.skill,
+    path: result.path,
+    stats: result.stats,
+    groups: result.groups.map((g) => ({
+      id: g.id,
+      titleKey: g.titleKey,
+      verdict: g.verdict,
+      checks: g.checks.map((c) => ({
+        id: c.id, status: c.status, detailKey: c.detailKey, detailVars: c.detailVars,
+      })),
+    })),
+  };
+}
+
+// A published report ends with one question: which host does the reader use. It is a poll, not a
+// feature -- one line, answered with a digit -- and it exists because a share count says how many
+// people read a report but not whether its trigger numbers apply to them. Codex has no skill item in
+// its event stream, so a Codex reader gets nothing from a trigger table; finding out that the readers
+// are mostly Codex users is cheap now and expensive to discover after building the wrong layer.
+// Deliberately absent from per-skill reports: the person reading one of those usually ran it.
+export function readerPollSection() {
+  return ['', '---', '', `## ${t('poll.title')}`, '', t('poll.body'), '', `> ${t('poll.why')}`].join('\n');
+}

package/lib/runs.js

@@ -0,0 +1,167 @@
+// Trial records are the only artefact that cannot be regenerated cheaply.
+//
+// The report is a rendering of them, a scorecard is a rendering of the directory, but the 110
+// records behind a trigger number cost ten minutes and real money. Until now they lived in memory
+// and died with the process, so nothing could be recomputed later, two runs could not be compared,
+// and a community submission had no file to submit.
+//
+// The shape copies the Python runner deliberately: meta.json first, then one JSON line per finished
+// trial, then summary.json. A run killed by Ctrl-C, a quota limit or a closed laptop keeps
+// everything it already finished, and a reader can tell from the files exactly what conditions
+// produced them.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const RUNNER_VERSION = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8')).version;
+
+export const RUN_SCHEMA = 'skillgauntlet/run/1';
+export { RUNNER_VERSION };
+
+export function runsRoot(skillDir) {
+  return path.join(skillDir, '.skillgauntlet', 'runs');
+}
+
+function stamp(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-`
+    + `${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+// rename over an existing file can fail on Windows, so fall back to remove-then-rename.
+function writeAtomic(file, text) {
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, text);
+  try {
+    fs.renameSync(tmp, file);
+  } catch {
+    fs.rmSync(file, { force: true });
+    fs.renameSync(tmp, file);
+  }
+}
+
+export function querySetHash(queries) {
+  return createHash('sha256').update(JSON.stringify(queries)).digest('hex').slice(0, 16);
+}
+
+// A second run started within the same second would otherwise reuse the first one's directory and
+// overwrite its records without a word. Fast failures and a re-run from a script do exactly that.
+function uniqueDir(root, base) {
+  let id = base;
+  let n = 1;
+  while (fs.existsSync(path.join(root, id))) {
+    n += 1;
+    id = `${base}-${n}`;
+  }
+  return id;
+}
+
+// Open a run before the first trial, so an interrupted run still has its conditions on disk.
+export function openRun({ skillDir, skillName, host, backend, model, runs, maxExplore, depth, querySets, queries, skillFingerprint }) {
+  const root = runsRoot(skillDir);
+  fs.mkdirSync(root, { recursive: true });
+  const runId = uniqueDir(root, stamp());
+  const dir = path.join(root, runId);
+  fs.mkdirSync(dir);
+
+  const meta = {
+    schema: RUN_SCHEMA,
+    runId,
+    runnerVersion: RUNNER_VERSION,
+    skill: skillName,
+    host,
+    backend,
+    model,
+    runs,
+    maxExplore,
+    depth,
+    querySets,
+    skillFingerprint: skillFingerprint || null,
+    platform: `${os.platform()} ${os.release()} / Node ${process.version}`,
+    startedAt: new Date().toISOString(),
+    finishedAt: null,
+    trials: 0,
+    interrupted: false,
+  };
+  const metaFile = path.join(dir, 'meta.json');
+  const rawFile = path.join(dir, 'raw.jsonl');
+  writeAtomic(metaFile, `${JSON.stringify(meta, null, 2)}\n`);
+  fs.writeFileSync(rawFile, '');
+  // The questions themselves, so a resume works from exactly what this run asked and not from a cache
+  // that may have been redrafted since. Its hash is meta.querySets[0].sha256.
+  if (queries) writeAtomic(path.join(dir, 'queries.json'), `${JSON.stringify(queries, null, 2)}\n`);
+  return handle(dir, meta);
+}
+
+// Shared by a new run and a resumed one: appending, refreshing and closing behave the same.
+function handle(dir, meta) {
+  const metaFile = path.join(dir, 'meta.json');
+  const rawFile = path.join(dir, 'raw.jsonl');
+  const flushMeta = () => writeAtomic(metaFile, `${JSON.stringify(meta, null, 2)}\n`);
+
+  return {
+    dir,
+    meta,
+    // Merge run-level facts learned mid-run (the tool list from the first init event, a stop reason).
+    patch(fields) {
+      Object.assign(meta, fields);
+      flushMeta();
+    },
+    get file() { return rawFile; },
+    // Called from the worker pool: appending is synchronous, so two in-flight trials cannot interleave
+    // a half line. Refreshing meta every trial would be wasteful; every 25 matches the Python runner.
+    append(row) {
+      fs.appendFileSync(rawFile, `${JSON.stringify(row)}\n`);
+      meta.trials += 1;
+      if (meta.trials % 25 === 0) flushMeta();
+    },
+    close(summary, { interrupted = false } = {}) {
+      meta.finishedAt = new Date().toISOString();
+      meta.interrupted = interrupted;
+      flushMeta();
+      if (summary) writeAtomic(path.join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+      return dir;
+    },
+  };
+}
+
+// Open an existing run directory to continue it. The caller has already checked that the conditions
+// match (see resumeRun in execute.js); this only reopens the files and notes the resume.
+export function reopenRun(dir) {
+  const { meta, records } = readRun(dir);
+  meta.trials = records.length;
+  meta.finishedAt = null;
+  meta.interrupted = false;
+  delete meta.stoppedAt;
+  delete meta.stoppedReason;
+  meta.resumedAt = [...(meta.resumedAt || []), new Date().toISOString()];
+  fs.rmSync(path.join(dir, 'summary.json'), { force: true });
+  const h = handle(dir, meta);
+  h.patch({});
+  return h;
+}
+
+// One valid record per (query, run index): the latest that is not an error or timeout. Failed trials
+// stay in raw.jsonl as evidence but are retried on resume and never counted.
+export function validRecords(records) {
+  const byKey = new Map();
+  for (const r of records) {
+    if (r.verdict === 'error' || r.verdict === 'timeout') continue;
+    byKey.set(`${r.queryId}#${r.run}`, r);
+  }
+  return [...byKey.values()];
+}
+
+// Rebuilding a report from a saved run is the reason the records are kept: the statistics can be
+// corrected without spending another token.
+export function readRun(dir) {
+  const meta = JSON.parse(fs.readFileSync(path.join(dir, 'meta.json'), 'utf8'));
+  const raw = fs.readFileSync(path.join(dir, 'raw.jsonl'), 'utf8')
+    .split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+  let summary = null;
+  try { summary = JSON.parse(fs.readFileSync(path.join(dir, 'summary.json'), 'utf8')); } catch { /* unfinished */ }
+  return { meta, records: raw, summary };
+}

package/lib/spawn.js

@@ -0,0 +1,84 @@
+// Launching a CLI on Windows. Three traps, all of which produce confusing errors rather than loud
+// ones: `where` returns the extension-less shim first (Node cannot exec it), `shell: true` re-splits
+// arguments on spaces (a prompt becomes several arguments), and cmd.exe treats & | < > ^ % specially.
+//
+// The way out is to not use a shell: run the package's JS entry with the current node binary. Only
+// when that cannot be found do we fall back to the .cmd shim, and then every argument is quoted.
+import fs from 'node:fs';
+import path from 'node:path';
+
+function looksLikeJs(p) {
+  return /\.(c|m)?js$/i.test(p);
+}
+
+// An npm .cmd shim names the script it runs (`"%_prog%" "%dp0%\<relative path>" %*`). Reading it is exact;
+// guessing from the package layout can land on a dependency's index.js instead of the CLI.
+function entryFromShim(bin) {
+  if (!/\.cmd$/i.test(bin)) return null;
+  let text;
+  try { text = fs.readFileSync(bin, 'utf8'); } catch { return null; }
+  const hits = [...text.matchAll(/"%_prog%"\s+"%dp0%\\([^"]+)"/g)];
+  if (!hits.length) return null;
+  const target = path.join(path.dirname(bin), ...hits[hits.length - 1][1].split('\\'));
+  try { return fs.statSync(target).isFile() ? target : null; } catch { return null; }
+}
+
+// Global npm layouts put the entry at node_modules/<pkg>/bin/<name>.js or
+// node_modules/@scope/<pkg>/<entry>.js. Look a bounded distance, in that order.
+function findJsEntry(bin, name) {
+  const fromShim = entryFromShim(bin);
+  if (fromShim) return fromShim;
+  const root = path.dirname(bin);
+  // A project-local install keeps its shims in node_modules/.bin, so the packages are one level up.
+  const nm = path.basename(root) === '.bin' ? path.dirname(root) : path.join(root, 'node_modules');
+  const candidates = [
+    path.join(nm, name, 'bin', `${name}.js`),
+    path.join(nm, name, `${name}.js`),
+    path.join(nm, name, 'cli.js'),
+    path.join(nm, name, 'index.js'),
+  ];
+  let entries = [];
+  try { entries = fs.readdirSync(nm, { withFileTypes: true }); } catch { return null; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name.startsWith('@')) {
+      let scoped = [];
+      try { scoped = fs.readdirSync(path.join(nm, e.name), { withFileTypes: true }); } catch { continue; }
+      for (const s of scoped) {
+        if (!s.isDirectory()) continue;
+        candidates.push(path.join(nm, e.name, s.name, 'bin', `${name}.js`));
+        candidates.push(path.join(nm, e.name, s.name, 'bin', name));
+        candidates.push(path.join(nm, e.name, s.name, `${name}.js`));
+        candidates.push(path.join(nm, e.name, s.name, 'cli.js'));
+        candidates.push(path.join(nm, e.name, s.name, 'index.js'));
+      }
+    }
+  }
+  return candidates.find((p) => { try { return fs.statSync(p).isFile(); } catch { return false; } });
+}
+
+export function runnerFor(bin, name = path.basename(bin).replace(/\.(cmd|bat|exe)$/i, '')) {
+  if (looksLikeJs(bin)) return { cmd: process.execPath, prefix: [bin], shell: false };
+  if (/\.exe$/i.test(bin)) return { cmd: bin, prefix: [], shell: false };
+  const entry = findJsEntry(bin, name);
+  if (entry) return { cmd: process.execPath, prefix: [entry], shell: false };
+  return { cmd: bin, prefix: [], shell: true };
+}
+
+// Only used on the shell fallback. Wraps each argument and neutralises cmd.exe metacharacters.
+export function quoteForCmd(arg) {
+  const s = String(arg);
+  if (!/[\s"&|<>^%()]/.test(s)) return s;
+  return `"${s.replace(/"/g, '""')}"`;
+}
+
+// Command, argument list and shell flag for one launch. Callers that used `shell: /\.(cmd|bat)$/` handed
+// the prompt to cmd.exe, which re-splits it on spaces; this routes every launch through runnerFor instead.
+export function launchSpec(bin, argv, name) {
+  const runner = runnerFor(bin, name);
+  return {
+    cmd: runner.cmd,
+    args: runner.shell ? [...runner.prefix, ...argv].map(quoteForCmd) : [...runner.prefix, ...argv],
+    shell: runner.shell,
+  };
+}

package/lib/static.js

@@ -0,0 +1,187 @@
+// Layer 0: static analysis. No model calls, no cost, reproducible: the same directory always
+// yields the same result. Reports facts and flags, never a single composite score -- a weighted
+// "87/100" cannot be audited or appealed, which is the one thing a rating must allow.
+//
+// Results carry message keys, not prose, so a scorecard is language-neutral and the report decides
+// how to word it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readFrontmatter } from './discover.js';
+
+const CODE_EXT = new Set(['.py', '.sh', '.bash', '.zsh', '.js', '.mjs', '.cjs', '.ts', '.ps1', '.rb', '.pl', '.exe', '.bat', '.cmd']);
+const SKIP_DIRS = new Set(['.git', 'node_modules', '__pycache__', '.cache', 'vendor', 'dist', 'build']);
+
+const RE = {
+  network: /\b(curl|wget|nc\s|ncat|requests\.(get|post|put)|urllib\.request|httpx\.|axios|fetch\s*\(|XMLHttpRequest|Invoke-WebRequest)\b/gi,
+  exec: /\b(os\.system|os\.popen|subprocess\.(run|call|Popen|check_output)|child_process|execSync|spawnSync|eval\s*\(|exec\s*\(|Invoke-Expression)\b/g,
+  secrets: /(ANTHROPIC_API_KEY|OPENAI_API_KEY|DEEPSEEK_API_KEY|AWS_SECRET|GITHUB_TOKEN|NPM_TOKEN|process\.env|os\.environ|~\/\.ssh|\/\.ssh\/|id_rsa|\.aws\/credentials|\.npmrc|\.netrc)/g,
+  obfusc: /(base64\s+-d|atob\s*\(|fromCharCode|\\x[0-9a-fA-F]{2}\\x[0-9a-fA-F]{2}\\x[0-9a-fA-F]{2}|eval\(Buffer\.from)/g,
+  install: /(postinstall|preinstall|prepare"\s*:)/g,
+  hijack: /(ignore\s+(all\s+)?(previous|prior|above)\s+instructions|disregard\s+.{0,20}instructions|forget\s+(all\s+)?(previous|prior)|忽略(之前|以上|前面)的?(所有)?(指令|说明)|无视(之前|以上))/gi,
+  exfil: /(send|post|upload|exfiltrat|上传|发送|回传).{0,40}(https?:\/\/|webhook|\burl\b)/gi,
+  wide: /(\bany\b|\banything\b|\ball\s+tasks\b|\beverything\b|任何|所有任务|各种)/gi,
+  triggerWords: /\b(use when|use this when|use for|should be used|designed for|trigger|when)\b|当用户|使用时机|适用于|用于/gi,
+  extImage: /!\[[^\]]*\]\((https?:\/\/[^)\s]+)\)/g,
+  zeroWidth: /[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g,
+};
+
+function lineOf(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+function hits(text, re, limit = 5) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(text)) && out.length < limit) {
+    out.push({ line: lineOf(text, m.index), match: m[0].trim().slice(0, 60) });
+  }
+  return out;
+}
+
+export function estTokens(text) {
+  let cjk = 0;
+  let other = 0;
+  for (const ch of text) {
+    if (/[\u3400-\u9FFF\u3040-\u30FF\uAC00-\uD7AF]/.test(ch)) cjk += 1;
+    else other += 1;
+  }
+  return Math.round(cjk * 1 + other / 4);
+}
+
+function collect(skillDir) {
+  const files = [];
+  const walk = (dir, depth) => {
+    if (depth > 6 || files.length > 3000) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(p, depth + 1);
+      } else if (e.isFile()) {
+        let size = 0;
+        try { size = fs.statSync(p).size; } catch { /* ignore */ }
+        files.push({ path: p, rel: path.relative(skillDir, p).replace(/\\/g, '/'), ext: path.extname(e.name).toLowerCase(), size });
+      }
+    }
+  };
+  walk(skillDir, 0);
+  return files;
+}
+
+// A check carries its message keys and the variables to fill them.
+const check = (id, status, detailKey, detailVars, evidence) => ({
+  id,
+  titleKey: `check.${id}.title`,
+  status,
+  detailKey,
+  detailVars: detailVars || {},
+  evidence: evidence || [],
+});
+
+const total = (list) => list.reduce((a, c) => a + (c.size || 0), 0);
+const humanSize = (n) => (n >= 1048576 ? `${(n / 1048576).toFixed(2)} MB` : `${(n / 1024).toFixed(1)} KB`);
+
+export function analyze(skillDir) {
+  const dir = path.resolve(skillDir);
+  const { fm, text } = readFrontmatter(dir);
+  const files = collect(dir);
+  const codeFiles = files.filter((f) => CODE_EXT.has(f.ext));
+  const codeText = codeFiles.map((f) => {
+    try { return fs.readFileSync(f.path, 'utf8'); } catch { return ''; }
+  }).join('\n');
+  const body = text.replace(/^---[\s\S]*?---/, '');
+  const totalBytes = total(files);
+  const size = humanSize(totalBytes);
+  const tokens = estTokens(text);
+  const desc = fm.description || '';
+  const allowed = (fm['allowed-tools'] || fm.allowed_tools || '').trim();
+  const dmi = String(fm['disable-model-invocation'] || '').toLowerCase() === 'true';
+
+  // A. context cost -- what the skill adds to the window, and how much of it is always on
+  const A = [];
+  A.push(check('A1', tokens > 5000 ? 'fail' : tokens > 2000 ? 'warn' : 'pass',
+    tokens > 2000 ? 'check.A1.heavy' : 'check.A1.detail', { chars: text.length, tokens }));
+  A.push(check('A2', desc.length > 800 ? 'warn' : 'pass',
+    desc ? 'check.A2.detail' : 'check.A2.missing', { chars: desc.length }));
+  const refs = (body.match(/\b(references|reference|assets|scripts)\/[\w./-]+/g) || []).length;
+  A.push(check('A3', refs > 0 ? 'pass' : 'info', refs > 0 ? 'check.A3.detail' : 'check.A3.none', { n: refs }));
+  A.push(check('A4', totalBytes > 2 * 1048576 ? 'warn' : 'pass', 'check.A4.detail', { size, files: files.length }));
+
+  // B. permission surface -- what the host has to grant it
+  const B = [];
+  B.push(check('B1', allowed ? 'pass' : (codeFiles.length ? 'fail' : 'warn'),
+    allowed ? 'check.B1.declared' : 'check.B1.missing', { tools: allowed.slice(0, 120) }));
+  if (allowed) {
+    const wide = /Bash\(\s*\*?\s*\)|Bash\s*(,|$)|Write\(\*\*\)|Edit\(\*\*\)/.test(allowed);
+    B.push(check('B2', wide ? 'fail' : 'pass', wide ? 'check.B2.wide' : 'check.B2.narrow'));
+  }
+  B.push(check('B3', dmi ? 'info' : 'pass', dmi ? 'check.B3.manual' : 'check.B3.auto'));
+  B.push(check('B4', codeFiles.length ? 'info' : 'pass',
+    codeFiles.length ? 'check.B4.detail' : 'check.B4.none',
+    { n: codeFiles.length, list: codeFiles.slice(0, 6).map((f) => f.rel).join(', ') }));
+
+  // C. code risk -- facts, escalated only when the permission surface is undeclared
+  const undeclared = !allowed && codeFiles.length > 0;
+  const C = [];
+  for (const [id, re] of [['C1', RE.network], ['C2', RE.exec], ['C3', RE.secrets], ['C4', RE.obfusc], ['C5', RE.install]]) {
+    const h = hits(codeText, re);
+    const detailKey = h.length ? (undeclared ? 'check.C.escalated' : 'check.C.hits') : 'check.C.none';
+    C.push(check(id, h.length ? (undeclared ? 'warn' : 'info') : 'pass', detailKey, { n: h.length }, h));
+  }
+
+  // D. instruction hijacking -- aimed at the reader, not the shell
+  const D = [];
+  const dh = hits(text, RE.hijack);
+  D.push(check('D1', dh.length ? 'fail' : 'pass', dh.length ? 'check.D1.hit' : 'check.D.none', {}, dh));
+  const sec = hits(text, RE.secrets);
+  D.push(check('D2', sec.length ? 'warn' : 'pass', sec.length ? 'check.D2.hit' : 'check.D.none', {}, sec));
+  const ex = hits(text, RE.exfil);
+  D.push(check('D3', ex.length ? 'warn' : 'pass', ex.length ? 'check.D3.hit' : 'check.D.none', {}, ex));
+  const zw = hits(text, RE.zeroWidth);
+  D.push(check('D4', zw.length ? 'fail' : 'pass', zw.length ? 'check.D4.hit' : 'check.D.none', {}, zw));
+  const img = hits(text, RE.extImage);
+  D.push(check('D5', img.length ? 'warn' : 'pass', img.length ? 'check.D5.hit' : 'check.D.none', {}, img));
+
+  // E. description quality -- the only layer that is also the trigger layer's input
+  const E = [];
+  E.push(check('E1', desc ? 'pass' : 'fail', desc ? 'check.E1.detail' : 'check.E1.missing', { chars: desc.length }));
+  const tw = hits(desc, RE.triggerWords, 1);
+  E.push(check('E2', tw.length ? 'pass' : 'warn', tw.length ? 'check.E2.hit' : 'check.E2.miss'));
+  const wide = hits(desc, RE.wide, 1);
+  E.push(check('E3', wide.length ? 'warn' : 'pass', wide.length ? 'check.E3.hit' : 'check.E3.none', {}, wide));
+  const clauses = (desc.match(/\bor\b|、|，|,|\//g) || []).length + 1;
+  E.push(check('E4', 'info', 'check.E4.detail', { n: clauses }));
+  const dirName = path.basename(dir);
+  E.push(check('E5', fm.name && fm.name !== dirName ? 'warn' : 'pass',
+    fm.name ? 'check.E5.detail' : 'check.E5.noname', { name: fm.name || '', dir: dirName }));
+
+  const groups = [
+    { id: 'A', titleKey: 'group.A', checks: A },
+    { id: 'B', titleKey: 'group.B', checks: B },
+    { id: 'C', titleKey: 'group.C', checks: C },
+    { id: 'D', titleKey: 'group.D', checks: D },
+    { id: 'E', titleKey: 'group.E', checks: E },
+  ];
+  for (const g of groups) {
+    g.verdict = g.checks.some((c) => c.status === 'fail') ? 'fail'
+      : g.checks.some((c) => c.status === 'warn') ? 'warn' : 'pass';
+  }
+  return {
+    skill: fm.name || path.basename(dir),
+    path: dir,
+    groups,
+    stats: {
+      files: files.length,
+      codeFiles: codeFiles.length,
+      bytes: totalBytes,
+      size,
+      skillMdChars: text.length,
+      skillMdTokens: tokens,
+      descriptionChars: desc.length,
+      allowedTools: allowed || null,
+      disableModelInvocation: dmi,
+    },
+  };
+}