From d02634189b8ffa178e7b9186868caccbe204a330 Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Tue, 9 Jun 2026 14:42:40 -0400
Subject: [PATCH 1/8] ci: add lint-skill-entry structural validator for skill
 contributions

Adds a CI gate that validates skill contributions against the documented
schema, reusing the installer's own parser (collectSkills / parseFrontmatter)
so it checks what actually ships rather than a parallel model.

- tools/skill-schema.mjs: single source for the frontmatter fields, maturity
  vocabulary, bundle-dir allowlist, description ceiling, and name pattern.
- .github/scripts/lint-skill-entry.mjs: errors on layout/schema violations,
  warns on advisory issues. On-demand-only contract bans alwaysApply, and the
  sibling-dir allowlist rejects knowledge/.
- .github/workflows/lint-skill-entry.yml: gates PRs on changed skills only,
  so pre-existing drift never blocks an unrelated change.
- test/lint-skill-entry.test.mjs: fixture tests for pass and each violation.
---
 .github/scripts/lint-skill-entry.mjs   | 152 +++++++++++++++++++++++++
 .github/workflows/lint-skill-entry.yml |  33 ++++++
 package.json                           |   3 +-
 test/lint-skill-entry.test.mjs         | 110 ++++++++++++++++++
 tools/skill-schema.mjs                 |  36 ++++++
 5 files changed, 333 insertions(+), 1 deletion(-)
 create mode 100644 .github/scripts/lint-skill-entry.mjs
 create mode 100644 .github/workflows/lint-skill-entry.yml
 create mode 100644 test/lint-skill-entry.test.mjs
 create mode 100644 tools/skill-schema.mjs

diff --git a/.github/scripts/lint-skill-entry.mjs b/.github/scripts/lint-skill-entry.mjs
new file mode 100644
index 00000000..48789911
--- /dev/null
+++ b/.github/scripts/lint-skill-entry.mjs
@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+//
+// Structural validator for skill contributions.
+//
+// Reuses the installer's own parser (bin/metamask-skills.mjs collectSkills /
+// parseFrontmatter) so that it validates exactly what ships, rather than a
+// parallel model. Errors block; warnings advise. Exits non-zero on any error.
+//
+// Run against the repo:        node .github/scripts/lint-skill-entry.mjs
+// Run against another tree:     SKILLS_LINT_ROOT=/path node .github/scripts/lint-skill-entry.mjs
+
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { collectSkills, parseFrontmatter } from '../../bin/metamask-skills.mjs';
+import {
+  ALLOWED_SIBLING_DIRS,
+  DESCRIPTION_MAX,
+  INSTALLED_PREFIX,
+  KNOWN_FRONTMATTER,
+  KNOWN_REPOS,
+  MATURITY_VALUES,
+  NAME_PATTERN,
+  RECOMMENDED_SECTIONS,
+} from '../../tools/skill-schema.mjs';
+
+const ROOT = process.env.SKILLS_LINT_ROOT
+  ? path.resolve(process.env.SKILLS_LINT_ROOT)
+  : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const allowedSiblings = new Set(ALLOWED_SIBLING_DIRS);
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+export function lintSkill(skill) {
+  const errors = [];
+  const warnings = [];
+  const dirName = skill.id.slice(skill.domain.length + 1);
+
+  let raw;
+  try {
+    raw = parseFrontmatter(readFileSync(path.join(skill.path, 'skill.md'), 'utf8'));
+  } catch (error) {
+    return { errors: [`could not read skill.md: ${error.message}`], warnings };
+  }
+
+  if (!raw.name) {
+    errors.push('missing required `name` in frontmatter');
+  } else {
+    if (raw.name !== dirName) {
+      errors.push(`\`name\` "${raw.name}" must match the directory "${dirName}"`);
+    }
+    if (!NAME_PATTERN.test(raw.name)) {
+      errors.push(`\`name\` "${raw.name}" must be kebab-case`);
+    }
+    if (raw.name.startsWith(INSTALLED_PREFIX)) {
+      errors.push(`source \`name\` must not carry the \`${INSTALLED_PREFIX}\` prefix; the installer adds it`);
+    }
+  }
+
+  if (!raw.description) {
+    errors.push('missing required `description` in frontmatter');
+  } else if (raw.description.length > DESCRIPTION_MAX) {
+    errors.push(`\`description\` is ${raw.description.length} chars, over the ${DESCRIPTION_MAX}-char operator ceiling`);
+  }
+
+  if (raw.maturity && !MATURITY_VALUES.includes(raw.maturity)) {
+    errors.push(`\`maturity\` "${raw.maturity}" must be one of: ${MATURITY_VALUES.join(', ')}`);
+  }
+
+  // On-demand-only contract: a source skill must not force persistent loading.
+  if (raw.alwaysApply !== undefined && TRUTHY.has(String(raw.alwaysApply).toLowerCase())) {
+    errors.push('skills are on-demand only; remove `alwaysApply: true` (always-on guidance belongs in AGENTS.md)');
+  }
+
+  // Sibling directories: bundle dirs and repos/ only. knowledge/ is rejected.
+  let entries = [];
+  try {
+    entries = readdirSync(skill.path, { withFileTypes: true });
+  } catch {
+    // skill dir vanished mid-run; nothing to check
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && !allowedSiblings.has(entry.name)) {
+      errors.push(`unexpected directory "${entry.name}/" beside skill.md (allowed: ${[...allowedSiblings].join(', ')}); domain knowledge belongs in references/`);
+    }
+  }
+
+  for (const repo of skill.repos) {
+    if (!KNOWN_REPOS.includes(repo)) {
+      warnings.push(`repos/${repo}.md targets an unknown consumer (known: ${KNOWN_REPOS.join(', ')})`);
+    }
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!KNOWN_FRONTMATTER.includes(key) && key !== 'alwaysApply') {
+      warnings.push(`unknown frontmatter key "${key}"; operators silently ignore unrecognised keys (typo?)`);
+    }
+  }
+
+  for (const section of RECOMMENDED_SECTIONS) {
+    if (!new RegExp(`^#{1,4}\\s+${section}\\b`, 'imu').test(skill.body)) {
+      warnings.push(`missing recommended section "## ${section}"`);
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// Restrict to skills touched by the given file paths (the CI gate passes the
+// PR's changed files, so pre-existing drift in untouched skills never blocks an
+// unrelated change). With no paths, every skill is linted (a full audit).
+function skillsForPaths(skills, paths) {
+  const resolved = paths.map((file) => path.resolve(ROOT, file));
+  return skills.filter((skill) =>
+    resolved.some((file) => file === skill.path || file.startsWith(`${skill.path}${path.sep}`)),
+  );
+}
+
+function main() {
+  const paths = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
+  const all = collectSkills([ROOT]);
+  const skills = paths.length > 0 ? skillsForPaths(all, paths) : all;
+  let errorCount = 0;
+  let warningCount = 0;
+
+  for (const skill of skills) {
+    const { errors, warnings } = lintSkill(skill);
+    if (errors.length > 0 || warnings.length > 0) {
+      console.log(`\n${skill.id}`);
+      for (const message of errors) {
+        console.log(`  error:   ${message}`);
+      }
+      for (const message of warnings) {
+        console.log(`  warning: ${message}`);
+      }
+    }
+    errorCount += errors.length;
+    warningCount += warnings.length;
+  }
+
+  console.log(`\n${skills.length} skill(s) checked, ${errorCount} error(s), ${warningCount} warning(s).`);
+  // Set exitCode rather than process.exit() so buffered stdout flushes when it
+  // is a pipe (e.g. under CI or execFileSync), instead of being truncated.
+  process.exitCode = errorCount > 0 ? 1 : 0;
+}
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  main();
+}
diff --git a/.github/workflows/lint-skill-entry.yml b/.github/workflows/lint-skill-entry.yml
new file mode 100644
index 00000000..0ca4ec34
--- /dev/null
+++ b/.github/workflows/lint-skill-entry.yml
@@ -0,0 +1,33 @@
+name: Lint skill entries
+
+on:
+  pull_request:
+    paths:
+      - 'domains/**'
+      - 'tools/**'
+      - '.github/scripts/lint-skill-entry.mjs'
+      - '.github/workflows/lint-skill-entry.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  lint-skills:
+    name: Lint skill entries
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+
+      - name: Get changed skill files
+        id: changed
+        uses: tj-actions/changed-files@v45
+        with:
+          files: domains/**
+
+      - name: Lint changed skills
+        if: steps.changed.outputs.any_changed == 'true'
+        run: node .github/scripts/lint-skill-entry.mjs ${{ steps.changed.outputs.all_changed_files }}
diff --git a/package.json b/package.json
index d8ae935b..49f9d676 100644
--- a/package.json
+++ b/package.json
@@ -21,7 +21,8 @@
     "test": "node --test test/*.test.mjs",
     "pack:dry-run": "yarn pack --dry-run",
     "lint": "yarn lint:changelog",
-    "lint:changelog": "auto-changelog validate --formatter oxfmt"
+    "lint:changelog": "auto-changelog validate --formatter oxfmt",
+    "lint:skills": "node .github/scripts/lint-skill-entry.mjs"
   },
   "publishConfig": {
     "access": "public",
diff --git a/test/lint-skill-entry.test.mjs b/test/lint-skill-entry.test.mjs
new file mode 100644
index 00000000..4aa72fdf
--- /dev/null
+++ b/test/lint-skill-entry.test.mjs
@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, test } from 'node:test';
+
+const LINTER = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '.github',
+  'scripts',
+  'lint-skill-entry.mjs',
+);
+
+const roots = [];
+
+function makeRoot() {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'skill-lint-'));
+  roots.push(root);
+  return root;
+}
+
+afterEach(() => {
+  while (roots.length > 0) {
+    rmSync(roots.pop(), { recursive: true, force: true });
+  }
+});
+
+function writeSkill(root, domain, name, frontmatter, body) {
+  const dir = path.join(root, 'domains', domain, 'skills', name);
+  mkdirSync(dir, { recursive: true });
+  const defaultBody = '## When To Use\n\n- always\n\n## Workflow\n\n1. do the thing\n';
+  writeFileSync(path.join(dir, 'skill.md'), `---\n${frontmatter}\n---\n\n${body ?? defaultBody}`);
+  return dir;
+}
+
+function lint(root) {
+  const result = spawnSync(process.execPath, [LINTER], {
+    env: { ...process.env, SKILLS_LINT_ROOT: root },
+    encoding: 'utf8',
+  });
+  return { code: result.status, output: `${result.stdout}${result.stderr}` };
+}
+
+describe('lint-skill-entry', () => {
+  test('a well-formed skill passes', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: Write unit tests');
+    assert.equal(lint(root).code, 0);
+  });
+
+  test('missing name fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'description: x');
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /missing required `name`/u);
+  });
+
+  test('name not matching the directory fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: wrong-name\ndescription: x');
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /must match the directory/u);
+  });
+
+  test('a knowledge/ sibling directory fails (the conversion guarantee)', () => {
+    const root = makeRoot();
+    const dir = writeSkill(root, 'perps', 'fix-bug', 'name: fix-bug\ndescription: x');
+    mkdirSync(path.join(dir, 'knowledge'));
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /knowledge/u);
+  });
+
+  test('an mms- prefix in the source name fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'mms-unit', 'name: mms-unit\ndescription: x');
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /prefix/u);
+  });
+
+  test('a description over the operator ceiling fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(1100)}`);
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /operator ceiling/u);
+  });
+
+  test('an invalid maturity value fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x\nmaturity: beta');
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /maturity/u);
+  });
+
+  test('alwaysApply: true fails (on-demand-only contract)', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x\nalwaysApply: true');
+    const { code, output } = lint(root);
+    assert.equal(code, 1);
+    assert.match(output, /on-demand/u);
+  });
+});
diff --git a/tools/skill-schema.mjs b/tools/skill-schema.mjs
new file mode 100644
index 00000000..800d0c5b
--- /dev/null
+++ b/tools/skill-schema.mjs
@@ -0,0 +1,36 @@
+// Single source of truth for the skill contribution schema.
+//
+// Imported by the lint-skill-entry validator so that the documented schema and
+// the enforced schema cannot drift apart. The installer's bundle-directory list
+// in tools/install (Bash) mirrors BUNDLE_DIRS; keep the two in sync.
+
+export const REQUIRED_FRONTMATTER = ['name', 'description'];
+export const OPTIONAL_FRONTMATTER = ['maturity', 'mandatory', 'scope'];
+export const KNOWN_FRONTMATTER = [...REQUIRED_FRONTMATTER, ...OPTIONAL_FRONTMATTER];
+
+export const MATURITY_VALUES = ['experimental', 'stable', 'deprecated'];
+
+// Directories the installer copies alongside skill.md (see tools/install).
+export const BUNDLE_DIRS = ['references', 'scripts', 'assets', 'adapters'];
+
+// Directories allowed beside skill.md: the bundle dirs plus the repo-overlay
+// dir. Anything else (notably knowledge/) is rejected, because the installer
+// does not ship it and the reference would dangle post-install.
+export const ALLOWED_SIBLING_DIRS = [...BUNDLE_DIRS, 'repos'];
+
+export const KNOWN_REPOS = ['metamask-extension', 'metamask-mobile', 'core'];
+
+// The description is always loaded into the operator's discovery surface, so it
+// is the per-skill always-on cost. The ceiling is the per-operator minimum
+// (OpenCode caps description at 1024), so a description that passes here is
+// accepted by every target.
+export const DESCRIPTION_MAX = 1024;
+
+export const RECOMMENDED_SECTIONS = ['When To Use', 'Workflow'];
+
+// kebab-case, matching the name regex Claude Code and OpenCode require.
+export const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/u;
+
+// The installer prepends this to generated output names; source names must not
+// carry it.
+export const INSTALLED_PREFIX = 'mms-';

From ce975b26b5eaaf225a174d55217841b1baaa6b18 Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 15:17:21 -0400
Subject: [PATCH 2/8] Ship `workflows/`, allow `metadata`, and check the schema
 against the installer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Running the validator against `main` turned up three errors, two of which were
defects in the repo rather than in the check.

`workflows/` held 14 files across two `web3-tools` skills, referenced 22 times
from their bodies, and was absent from the installer's bundle list — so every
installed copy carried 22 dangling links and nothing reported it. Adding it to
`copy_bundle_dirs` makes all 22 resolve. This is the third instance of one root
cause, after `pr-validate`'s `hooks/` and domain `knowledge/`: a directory that
exists in source and is not in the copy list.

So the list stops being written down twice. Two tests now read `tools/install`
directly — one asserting `BUNDLE_DIRS` matches the directories it copies, one
asserting every key it reads via `frontmatter_value` is declared. The comment
asking a human to keep them in sync is now checked.

`metadata` was rejected as unknown frontmatter though README documents it as
preserved through install; it joins the optional set. Knowledge files get their
own declared keys, since they take `domain` rather than the installer-behaviour
keys skills use.

The `performance` description was 1078 characters against the 1024 operator
ceiling; trimmed to 928 without dropping a trigger or a covered topic.

Validator now reports 0 errors across 46 skills.
---
 .../performance/skills/performance/skill.md   |  2 +-
 test/lint-skill-entry.test.mjs                | 42 ++++++++++++++++++-
 tools/install                                 |  2 +-
 tools/skill-schema.mjs                        | 15 +++++--
 4 files changed, 54 insertions(+), 7 deletions(-)

diff --git a/domains/performance/skills/performance/skill.md b/domains/performance/skills/performance/skill.md
index dafe01cc..b0302e89 100644
--- a/domains/performance/skills/performance/skill.md
+++ b/domains/performance/skills/performance/skill.md
@@ -1,4 +1,4 @@
 ---
 name: performance
-description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time/websocket data, frequent updates, or large lists and wanting to avoid perf pitfalls before building; reviewing or auditing PRs/code for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; analyzing a captured `.cpuprofile` / React Native Release Profiler trace (e.g. a `sampling-profiler-trace*.cpuprofile`) to find why a flow is slow; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, trace() instrumentation, and Release Profiler CPU-profile analysis. Not for correctness bugs, styling/spacing, Solidity gas, or the browser extension.
+description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time data, frequent updates, or large lists; reviewing PRs for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; analyzing a captured `.cpuprofile` / React Native Release Profiler trace to find why a flow is slow; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, trace() instrumentation, and CPU-profile analysis. Not for correctness bugs, styling, Solidity gas, or the browser extension.
 ---
diff --git a/test/lint-skill-entry.test.mjs b/test/lint-skill-entry.test.mjs
index 4aa72fdf..26cf6757 100644
--- a/test/lint-skill-entry.test.mjs
+++ b/test/lint-skill-entry.test.mjs
@@ -1,10 +1,15 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, test } from 'node:test';
+import {
+  BUNDLE_DIRS,
+  KNOWN_FRONTMATTER,
+  KNOWN_KNOWLEDGE_FRONTMATTER,
+} from '../tools/skill-schema.mjs';
 
 const LINTER = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -108,3 +113,38 @@ describe('lint-skill-entry', () => {
     assert.match(output, /on-demand/u);
   });
 });
+
+describe('schema tracks the installer', () => {
+  // The schema and tools/install (Bash) describe the same facts in two languages. The
+  // comment in skill-schema.mjs asks a human to keep them in sync; these check it.
+  //
+  // Drift here is not cosmetic. `workflows/` existed in two web3-tools skills, was
+  // referenced 17 times from their bodies, and was absent from the installer's bundle
+  // list — so every installed copy carried 17 dangling links, and nothing reported it.
+  const INSTALL = readFileSync(
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'tools', 'install'),
+    'utf8',
+  );
+
+  test('BUNDLE_DIRS matches the directories tools/install copies', () => {
+    const m = /for bundle in ([\w\s]+); do/u.exec(INSTALL);
+    assert.ok(m, 'could not find the bundle loop in tools/install');
+    const shipped = m[1].trim().split(/\s+/u);
+    assert.deepEqual(
+      [...shipped].sort(),
+      [...BUNDLE_DIRS].sort(),
+      'tools/install ships a different set of directories than BUNDLE_DIRS declares',
+    );
+  });
+
+  test('the schema declares every frontmatter key tools/install reads', () => {
+    const read = [...INSTALL.matchAll(/frontmatter_value\s+"\$\w+"\s+"([\w-]+)"/gu)].map((x) => x[1]);
+    assert.ok(read.length > 0, 'expected frontmatter_value calls in tools/install');
+    const known = new Set([...KNOWN_FRONTMATTER, ...KNOWN_KNOWLEDGE_FRONTMATTER]);
+    assert.deepEqual(
+      [...new Set(read)].filter((k) => !known.has(k)),
+      [],
+      'tools/install reads a frontmatter key the schema does not declare',
+    );
+  });
+});
diff --git a/tools/install b/tools/install
index e39404aa..af56d281 100755
--- a/tools/install
+++ b/tools/install
@@ -346,7 +346,7 @@ write_user_codex() {
 copy_bundle_dirs() {
   local skill_dir="$1" dest_dir="$2" label="$3"
   local bundle
-  for bundle in references scripts assets adapters; do
+  for bundle in references scripts assets adapters workflows; do
     if [[ -d "$skill_dir/$bundle" ]]; then
       action "$label/$bundle/"
       $DRY_RUN && continue
diff --git a/tools/skill-schema.mjs b/tools/skill-schema.mjs
index 800d0c5b..fc89c6a5 100644
--- a/tools/skill-schema.mjs
+++ b/tools/skill-schema.mjs
@@ -5,17 +5,19 @@
 // in tools/install (Bash) mirrors BUNDLE_DIRS; keep the two in sync.
 
 export const REQUIRED_FRONTMATTER = ['name', 'description'];
-export const OPTIONAL_FRONTMATTER = ['maturity', 'mandatory', 'scope'];
+export const OPTIONAL_FRONTMATTER = ['maturity', 'mandatory', 'scope', 'metadata'];
 export const KNOWN_FRONTMATTER = [...REQUIRED_FRONTMATTER, ...OPTIONAL_FRONTMATTER];
 
 export const MATURITY_VALUES = ['experimental', 'stable', 'deprecated'];
 
 // Directories the installer copies alongside skill.md (see tools/install).
-export const BUNDLE_DIRS = ['references', 'scripts', 'assets', 'adapters'];
+export const BUNDLE_DIRS = ['references', 'scripts', 'assets', 'adapters', 'workflows'];
 
 // Directories allowed beside skill.md: the bundle dirs plus the repo-overlay
-// dir. Anything else (notably knowledge/) is rejected, because the installer
-// does not ship it and the reference would dangle post-install.
+// dir. Anything else is rejected, because the installer does not ship it and any
+// reference to it would dangle post-install. `knowledge/` is not listed here
+// because it is a per-DOMAIN directory, never a skill sibling; the installer
+// delivers it via copy_domain_knowledge.
 export const ALLOWED_SIBLING_DIRS = [...BUNDLE_DIRS, 'repos'];
 
 export const KNOWN_REPOS = ['metamask-extension', 'metamask-mobile', 'core'];
@@ -34,3 +36,8 @@ export const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/u;
 // The installer prepends this to generated output names; source names must not
 // carry it.
 export const INSTALLED_PREFIX = 'mms-';
+
+// Frontmatter permitted on a domain knowledge file. Knowledge files are a distinct
+// artifact from skills and take a different set — `domain` instead of `maturity`,
+// and none of the installer-behaviour keys.
+export const KNOWN_KNOWLEDGE_FRONTMATTER = ['name', 'domain', 'description'];

From 87f313d4415b950297313439d7fdef16bc8b83dd Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 15:27:53 -0400
Subject: [PATCH 3/8] Document the two admission questions the linter cannot
 answer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The validator covers the deterministic half of what makes a skill acceptable —
layout, name pattern, frontmatter keys, maturity, description length. It says
nothing about the two questions that decide whether a skill should exist, and
those are currently answered ad hoc in review.

The first is whether the thing is a skill at all. Skills shape generation;
linters, hooks, and fitness functions enforce. A skill that substitutes for
enforcement is unsafe, since an agent can ignore any context it is given. One
that restates what a deterministic check already verifies is wasteful, spending
context on every invocation to duplicate what CI produces for free. One that
teaches the upstream pattern so enforcement rarely fires is the right shape, and
should name the layer it pairs with.

The second is whether it earns its context budget. Frontmatter for every
installed skill loads at agent startup, so a skill that is never selected still
costs its description on every run.

Ships here rather than separately because the two halves are the same decision:
the check handles what it can, and the prose says where to spend review
attention instead. Adapted from the review of ADR 0057
(MetaMask/decisions#162).
---
 CONTRIBUTING.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9194bd9a..cbcb06e5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -18,6 +18,47 @@ A well-crafted skill should:
 - **Declare maturity** — Use `experimental`, `stable`, or `deprecated` in frontmatter
 - **Be well-documented** — Clear instructions, examples, and expected outcomes
 
+### Is it a skill, or does it belong in an enforcement layer?
+
+Skills shape generation. Linters, fitness functions, and hooks enforce. The two do
+different work, and any pattern load-bearing enough to encode probably wants both.
+
+| Layer | Mechanism | Can an agent bypass it? | Timing |
+|-------|-----------|-------------------------|--------|
+| Skills (`domains/<area>/skills/<name>/skill.md`) | Generation-time guidance | Yes — suggestive only | Before output |
+| AI rules (`AGENTS.md`, `.cursor/rules/*.mdc`, `CLAUDE.md`) | Context injection | Yes — suggestive only | Before output |
+| Hooks (Claude Code `PreToolUse`, Cursor hooks) | Runtime interception | No | At tool call |
+| Linters, fitness functions, CI | Validation | No | After output |
+
+Three ways a proposed skill fails this test:
+
+- **A skill that substitutes for enforcement is unsafe.** An agent can ignore any context
+  it is given, so anything that must not be bypassed belongs in a hook or a lint rule.
+- **A skill that restates what a deterministic check already verifies is wasteful.** It
+  spends context on every invocation to duplicate ground truth that CI produces for free.
+- **A skill that teaches the upstream pattern, so the enforcement layer rarely has to fire,
+  is the right shape.** An existing lint rule is evidence the pattern matters enough to
+  encode at both layers — name the layer the skill pairs with.
+
+The question to answer in review is not *"is this redundant with the linter?"* but *"is this
+doing generation-time work the linter cannot?"*
+
+### Does it earn its context budget?
+
+Frontmatter for every installed skill is loaded at agent startup, as fixed overhead that
+grows linearly with the catalogue. A skill that is never selected still costs its
+`description` on every run.
+
+- Not a duplicate of a skill that already exists — check `metamask-skills list` first.
+- Actionable rather than aspirational: steps an agent can follow, not principles to admire.
+- Scoped so a reader can tell when it applies — neither one repo's quirk nor "good code".
+- `description` within the ceiling in [`tools/skill-schema.mjs`](tools/skill-schema.mjs). It is
+  the lowest limit across operators, so a description that passes is accepted by all of them.
+
+`yarn lint:skills` checks the deterministic properties — directory layout, name pattern,
+frontmatter keys, maturity values, description length — so review time goes to the two
+questions above, which no check can answer.
+
 ## How to Contribute
 
 ### Adding a New Skill

From 105ecf0e3f2dc8d8c75c5f22e4b4cba7afef9ff0 Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 15:33:50 -0400
Subject: [PATCH 4/8] Address review: untrusted interpolation, path shape,
 changed-files coverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three blocking findings from @NicolasMassart.

Filenames were interpolated into the shell. They come from PR contents, so a
path with spaces split and a path with metacharacters could alter the command.
They are now produced by `git diff -z`, passed through the environment, and
split on NUL into an array — never placed on a command line. Requires
`fetch-depth: 0` for the base commit, and drops the `tj-actions/changed-files`
dependency.

Malformed directory shapes passed silently. `collectSkills` only returns
directories that already match the layout and parse, so a misplaced file, a
`SKILL.md` casing error, or a `skill.md` deleted in the same PR were invisible
to it — the run printed `0 skill(s) checked, 0 error(s)` and exited 0. Shape is
now checked from the path side, before the collect filter, which is where those
cases exist. All four examples in the review are covered.

The changed-files branch had no tests, which is how the above reached `main`:
every case exercised the no-argument full-audit path while CI runs the other
one. `lint()` now forwards paths, and the seven cases from the review are
covered — including a filename with a space, and a description at exactly
`DESCRIPTION_MAX` versus one over.

Verified non-vacuous: the pre-fix linter on the missing-`skill.md` fixture
prints `0 skill(s) checked, 0 error(s)` and exits 0; the same input now reports
the error.
---
 .github/scripts/lint-skill-entry.mjs   | 45 ++++++++++++++-
 .github/workflows/lint-skill-entry.yml | 27 +++++++--
 test/lint-skill-entry.test.mjs         | 78 +++++++++++++++++++++++++-
 3 files changed, 140 insertions(+), 10 deletions(-)

diff --git a/.github/scripts/lint-skill-entry.mjs b/.github/scripts/lint-skill-entry.mjs
index 48789911..75bccacf 100644
--- a/.github/scripts/lint-skill-entry.mjs
+++ b/.github/scripts/lint-skill-entry.mjs
@@ -9,7 +9,7 @@
 // Run against the repo:        node .github/scripts/lint-skill-entry.mjs
 // Run against another tree:     SKILLS_LINT_ROOT=/path node .github/scripts/lint-skill-entry.mjs
 
-import { readFileSync, readdirSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -117,13 +117,52 @@ function skillsForPaths(skills, paths) {
   );
 }
 
+// A changed path under domains/ must live at domains/<domain>/skills/<name>/… and that
+// skill root must have a readable skill.md.
+//
+// This has to run BEFORE the collectSkills filter, not inside the per-skill loop.
+// collectSkills only returns directories that already match the expected layout and parse,
+// so anything malformed is invisible to it — a misplaced file, a SKILL.md casing error, or
+// a skill.md deleted in the same PR all produced "0 skill(s) checked, 0 error(s)" and a
+// green run. The shape has to be checked from the path side, where the malformed cases
+// actually exist.
+export const SKILL_PATH = /^domains\/([^/]+)\/skills\/([^/]+)\/(?:[^/]+\/)*[^/]+$/u;
+
+export function validatePathShape(file, root = ROOT) {
+  const normalized = file.split(path.sep).join('/');
+  if (!normalized.startsWith('domains/')) {
+    return null;
+  }
+  const match = SKILL_PATH.exec(normalized);
+  if (!match) {
+    return `path "${normalized}" is not under domains/<domain>/skills/<name>/`;
+  }
+  const [, domain, name] = match;
+  const skillRoot = path.join(root, 'domains', domain, 'skills', name);
+  try {
+    statSync(path.join(skillRoot, 'skill.md'));
+  } catch {
+    return `skill root "domains/${domain}/skills/${name}/" has no readable skill.md`;
+  }
+  return null;
+}
+
 function main() {
   const paths = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
-  const all = collectSkills([ROOT]);
-  const skills = paths.length > 0 ? skillsForPaths(all, paths) : all;
   let errorCount = 0;
   let warningCount = 0;
 
+  for (const file of paths) {
+    const problem = validatePathShape(file);
+    if (problem) {
+      console.log(`\nerror:   ${problem}`);
+      errorCount += 1;
+    }
+  }
+
+  const all = collectSkills([ROOT]);
+  const skills = paths.length > 0 ? skillsForPaths(all, paths) : all;
+
   for (const skill of skills) {
     const { errors, warnings } = lintSkill(skill);
     if (errors.length > 0 || warnings.length > 0) {
diff --git a/.github/workflows/lint-skill-entry.yml b/.github/workflows/lint-skill-entry.yml
index 0ca4ec34..360b561e 100644
--- a/.github/workflows/lint-skill-entry.yml
+++ b/.github/workflows/lint-skill-entry.yml
@@ -17,17 +17,34 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          # Need the base commit to diff against.
+          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
           node-version: 24.x
 
-      - name: Get changed skill files
+      # Filenames come from PR contents, so they are untrusted input. They are read
+      # NUL-delimited, passed through the environment, and split on NUL into an array —
+      # never interpolated into a command line. A path containing a space, a quote, or a
+      # shell metacharacter is therefore just a filename.
+      - name: Collect changed skill files
         id: changed
-        uses: tj-actions/changed-files@v45
-        with:
-          files: domains/**
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          git diff -z --name-only --diff-filter=d "$BASE_SHA" "$HEAD_SHA" -- 'domains/**' \
+            > changed-skill-files.bin
+          if [[ -s changed-skill-files.bin ]]; then
+            echo "any_changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "any_changed=false" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Lint changed skills
         if: steps.changed.outputs.any_changed == 'true'
-        run: node .github/scripts/lint-skill-entry.mjs ${{ steps.changed.outputs.all_changed_files }}
+        run: |
+          mapfile -d '' -t files < changed-skill-files.bin
+          node .github/scripts/lint-skill-entry.mjs "${files[@]}"
diff --git a/test/lint-skill-entry.test.mjs b/test/lint-skill-entry.test.mjs
index 26cf6757..36852b76 100644
--- a/test/lint-skill-entry.test.mjs
+++ b/test/lint-skill-entry.test.mjs
@@ -8,6 +8,7 @@ import { afterEach, describe, test } from 'node:test';
 import {
   BUNDLE_DIRS,
   KNOWN_FRONTMATTER,
+  DESCRIPTION_MAX,
   KNOWN_KNOWLEDGE_FRONTMATTER,
 } from '../tools/skill-schema.mjs';
 
@@ -41,8 +42,8 @@ function writeSkill(root, domain, name, frontmatter, body) {
   return dir;
 }
 
-function lint(root) {
-  const result = spawnSync(process.execPath, [LINTER], {
+function lint(root, ...paths) {
+  const result = spawnSync(process.execPath, [LINTER, ...paths], {
     env: { ...process.env, SKILLS_LINT_ROOT: root },
     encoding: 'utf8',
   });
@@ -148,3 +149,76 @@ describe('schema tracks the installer', () => {
     );
   });
 });
+
+// The workflow invokes the linter WITH changed-file arguments. Every test above runs the
+// no-argument full-audit branch, so the branch CI actually depends on had no coverage —
+// which is how malformed paths reached main. These mirror the CI invocation.
+describe('changed-files mode', () => {
+  test('a changed skill.md is linted', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x');
+    const { code, output } = lint(root, 'domains/testing/skills/unit-testing/skill.md');
+    assert.equal(code, 0, output);
+    assert.match(output, /1 skill\(s\) checked/u);
+  });
+
+  test('a changed reference file maps back to its skill root', () => {
+    const root = makeRoot();
+    const dir = writeSkill(root, 'testing', 'unit-testing', 'name: wrong-name\ndescription: x');
+    mkdirSync(path.join(dir, 'references'), { recursive: true });
+    writeFileSync(path.join(dir, 'references', 'foo.md'), '# foo\n');
+    const { code, output } = lint(root, 'domains/testing/skills/unit-testing/references/foo.md');
+    assert.equal(code, 1, output);
+    assert.match(output, /must match the directory/u, 'should lint the owning skill, not just the file');
+  });
+
+  test('a malformed domains path fails', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x');
+    const { code, output } = lint(root, 'domains/testing/bar/skill.md');
+    assert.equal(code, 1, output);
+    assert.match(output, /is not under domains\/<domain>\/skills\/<name>\//u);
+  });
+
+  test('a changed path whose skill.md is missing is reported, not skipped', () => {
+    const root = makeRoot();
+    // Skill-shaped directory, no skill.md — the case that previously printed
+    // "0 skill(s) checked, 0 error(s)" and exited 0.
+    mkdirSync(path.join(root, 'domains', 'testing', 'skills', 'ghost', 'references'), {
+      recursive: true,
+    });
+    writeFileSync(path.join(root, 'domains', 'testing', 'skills', 'ghost', 'references', 'a.md'), 'x');
+    const { code, output } = lint(root, 'domains/testing/skills/ghost/references/a.md');
+    assert.equal(code, 1, output);
+    assert.match(output, /has no readable skill\.md/u);
+  });
+
+  test('a filename containing spaces survives argv handling', () => {
+    const root = makeRoot();
+    const dir = writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x');
+    writeFileSync(path.join(dir, 'references file.md'), '# spaced\n');
+    const { code, output } = lint(root, 'domains/testing/skills/unit-testing/references file.md');
+    assert.equal(code, 0, output);
+    assert.match(output, /1 skill\(s\) checked/u, 'the path should resolve as one argument');
+  });
+
+  test('warnings-only input exits 0', () => {
+    const root = makeRoot();
+    writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x', '# no sections\n');
+    const { code, output } = lint(root, 'domains/testing/skills/unit-testing/skill.md');
+    assert.equal(code, 0, output);
+    assert.match(output, /warning:/u);
+  });
+
+  test('a description of exactly DESCRIPTION_MAX passes, +1 fails', () => {
+    const atLimit = makeRoot();
+    writeSkill(atLimit, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(DESCRIPTION_MAX)}`);
+    assert.equal(lint(atLimit, 'domains/testing/skills/unit-testing/skill.md').code, 0);
+
+    const overLimit = makeRoot();
+    writeSkill(overLimit, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(DESCRIPTION_MAX + 1)}`);
+    const { code, output } = lint(overLimit, 'domains/testing/skills/unit-testing/skill.md');
+    assert.equal(code, 1, output);
+    assert.match(output, /over the \d+-char operator ceiling/u);
+  });
+});

From b197ebcc978088747e6deb3ae819af35d0587a0a Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 15:36:58 -0400
Subject: [PATCH 5/8] Address the remaining review suggestions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`tools/**` triggered the workflow but never reached the lint step: the file
filter listed only `domains/**`, so a schema change spun CI up, found no changed
skills, skipped, and reported green — the tightened rule never applied to what
already existed. A change under `tools/` or `.github/scripts/` now runs the full
audit instead.

`scope` and `mandatory` had no enum validation, so `scope: users` or
`mandatory: ture` were silent no-ops that installed differently than intended.
Both now warn, matching the `maturity` check without widening the blocking
surface.

The recommended-section regex used a trailing `\b`, which let
`## When To Use Cases` satisfy `When To Use`. Anchoring to end-of-line fixes that
but rejects `## Workflows` and `## Workflow (interactive)`, both of which are the
section and both of which exist here — so the pattern allows an optional plural
and an optional parenthetical, nothing else. The reviewer's case is still
rejected; the four false positives anchoring introduced are gone.

`collectSkills` was called with `repo` undefined and worked only because the
linter never reads `repoApplicable`; it now passes an explicit sentinel.

README, CONTRIBUTING, and SKILL_TEMPLATE all documented a 1,536-character
description while the validator enforces 1,024. All three now say 1,024, with
the reason recorded once: it is the lowest ceiling across operators.

`lint:skills` is renamed `audit:skills`, since with no arguments it audits the
whole catalogue rather than linting a change. The post-merge failure the review
anticipated no longer applies — the full audit is clean.

The sibling-directory test used `knowledge/`; `workflows/` was the live failure
mode but is now legitimately in the bundle list, so the test asserts the general
guarantee instead: a sibling the installer does not copy fails, and every
directory in `BUNDLE_DIRS` is accepted.
---
 .github/SKILL_TEMPLATE.md              |  2 +-
 .github/scripts/lint-skill-entry.mjs   | 23 +++++++++++++++++++++--
 .github/workflows/lint-skill-entry.yml | 15 ++++++++++++++-
 CONTRIBUTING.md                        |  4 ++--
 README.md                              |  6 +++++-
 package.json                           |  2 +-
 test/lint-skill-entry.test.mjs         | 23 +++++++++++++++++++++++
 tools/skill-schema.mjs                 |  3 +++
 8 files changed, 70 insertions(+), 8 deletions(-)

diff --git a/.github/SKILL_TEMPLATE.md b/.github/SKILL_TEMPLATE.md
index 0437c846..76f8726d 100644
--- a/.github/SKILL_TEMPLATE.md
+++ b/.github/SKILL_TEMPLATE.md
@@ -12,7 +12,7 @@ name: example-skill
 description: >-
   One or two sentences: what the skill does, plus when_to_use cues
   (e.g. "Use when asked to …, or for …"). Keep the full description
-  within 1,536 characters.
+  within 1,024 characters.
 maturity: stable
 ---
 
diff --git a/.github/scripts/lint-skill-entry.mjs b/.github/scripts/lint-skill-entry.mjs
index 75bccacf..780bbdc5 100644
--- a/.github/scripts/lint-skill-entry.mjs
+++ b/.github/scripts/lint-skill-entry.mjs
@@ -22,6 +22,7 @@ import {
   KNOWN_REPOS,
   MATURITY_VALUES,
   NAME_PATTERN,
+  SCOPE_VALUES,
   RECOMMENDED_SECTIONS,
 } from '../../tools/skill-schema.mjs';
 
@@ -31,6 +32,7 @@ const ROOT = process.env.SKILLS_LINT_ROOT
 
 const allowedSiblings = new Set(ALLOWED_SIBLING_DIRS);
 const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['0', 'false', 'no', 'off']);
 
 export function lintSkill(skill) {
   const errors = [];
@@ -68,6 +70,17 @@ export function lintSkill(skill) {
     errors.push(`\`maturity\` "${raw.maturity}" must be one of: ${MATURITY_VALUES.join(', ')}`);
   }
 
+  // `scope` and `mandatory` change installer behaviour, and a typo in either is a silent
+  // no-op today: the key is accepted, no enum runs, and the skill installs in a way the
+  // author did not intend. `scope: users` falls back to project scope; `mandatory: ture`
+  // is falsy. Warnings rather than errors — the blocking surface stays small.
+  if (raw.scope !== undefined && !SCOPE_VALUES.includes(raw.scope)) {
+    warnings.push(`\`scope\` "${raw.scope}" is not one of: ${SCOPE_VALUES.join(', ')} (installs as project scope)`);
+  }
+  if (raw.mandatory !== undefined && !TRUTHY.has(String(raw.mandatory).toLowerCase()) && !FALSY.has(String(raw.mandatory).toLowerCase())) {
+    warnings.push(`\`mandatory\` "${raw.mandatory}" is neither truthy nor falsy (treated as false)`);
+  }
+
   // On-demand-only contract: a source skill must not force persistent loading.
   if (raw.alwaysApply !== undefined && TRUTHY.has(String(raw.alwaysApply).toLowerCase())) {
     errors.push('skills are on-demand only; remove `alwaysApply: true` (always-on guidance belongs in AGENTS.md)');
@@ -99,7 +112,11 @@ export function lintSkill(skill) {
   }
 
   for (const section of RECOMMENDED_SECTIONS) {
-    if (!new RegExp(`^#{1,4}\\s+${section}\\b`, 'imu').test(skill.body)) {
+    // A trailing `\b` let `## When To Use Cases` satisfy `When To Use` — a different
+    // section. Anchoring to end-of-line fixes that but rejects `## Workflows` and
+    // `## Workflow (interactive)`, both of which are the section, and both of which exist
+    // in this corpus. So: optional plural, optional parenthetical qualifier, nothing else.
+    if (!new RegExp(`^#{1,4}\\s+${section}s?(?:\\s*\\([^)]*\\))?\\s*$`, 'imu').test(skill.body)) {
       warnings.push(`missing recommended section "## ${section}"`);
     }
   }
@@ -160,7 +177,9 @@ function main() {
     }
   }
 
-  const all = collectSkills([ROOT]);
+  // '*' rather than undefined: the linter never reads repoApplicable, but relying on that
+  // would break silently if `repo` became required.
+  const all = collectSkills([ROOT], '*');
   const skills = paths.length > 0 ? skillsForPaths(all, paths) : all;
 
   for (const skill of skills) {
diff --git a/.github/workflows/lint-skill-entry.yml b/.github/workflows/lint-skill-entry.yml
index 360b561e..ec61349a 100644
--- a/.github/workflows/lint-skill-entry.yml
+++ b/.github/workflows/lint-skill-entry.yml
@@ -43,8 +43,21 @@ jobs:
             echo "any_changed=false" >> "$GITHUB_OUTPUT"
           fi
 
+          # A schema or installer change re-validates the whole catalogue. Without this the
+          # workflow triggers on tools/**, finds no changed skill files, skips the lint step,
+          # and reports green — so a tightened rule is never applied to what already exists.
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- tools/ .github/scripts/ | grep -q .; then
+            echo "full_audit=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "full_audit=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Audit every skill (schema or installer changed)
+        if: steps.changed.outputs.full_audit == 'true'
+        run: node .github/scripts/lint-skill-entry.mjs
+
       - name: Lint changed skills
-        if: steps.changed.outputs.any_changed == 'true'
+        if: steps.changed.outputs.full_audit != 'true' && steps.changed.outputs.any_changed == 'true'
         run: |
           mapfile -d '' -t files < changed-skill-files.bin
           node .github/scripts/lint-skill-entry.mjs "${files[@]}"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cbcb06e5..45b7d51a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -55,7 +55,7 @@ grows linearly with the catalogue. A skill that is never selected still costs it
 - `description` within the ceiling in [`tools/skill-schema.mjs`](tools/skill-schema.mjs). It is
   the lowest limit across operators, so a description that passes is accepted by all of them.
 
-`yarn lint:skills` checks the deterministic properties — directory layout, name pattern,
+`yarn audit:skills` checks the deterministic properties — directory layout, name pattern,
 frontmatter keys, maturity values, description length — so review time goes to the two
 questions above, which no check can answer.
 
@@ -170,7 +170,7 @@ Your `skill.md` should include YAML frontmatter plus body content:
 ```yaml
 ---
 name: <slash-command-name>
-description: <≤1,536 chars including when_to_use cues>
+description: <≤1,024 chars including when_to_use cues>
 maturity: stable          # experimental | stable | deprecated
 ---
 ```
diff --git a/README.md b/README.md
index c0954790..1a4ae919 100644
--- a/README.md
+++ b/README.md
@@ -382,7 +382,7 @@ domains/<area>/
 ```yaml
 ---
 name: <slash-command-name>
-description: <≤1,536 chars including when_to_use cues>
+description: <≤1,024 chars including when_to_use cues>
 maturity: stable          # experimental | stable | deprecated (default stable)
 ---
 ```
@@ -391,6 +391,10 @@ Extra metadata blocks (e.g. OpenClaw-style `metadata:` with emoji and
 homepage) are preserved through install — only `name`, `description`,
 `maturity`, `mandatory`, and `scope` are read by the CLI.
 
+The 1,024-character ceiling is the lowest limit across operators, so a description
+that fits is accepted by all of them. It is enforced by `yarn audit:skills` from
+[`tools/skill-schema.mjs`](tools/skill-schema.mjs), which is the source of truth.
+
 ### Overlay frontmatter
 
 ```yaml
diff --git a/package.json b/package.json
index 49f9d676..d2b992bf 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "pack:dry-run": "yarn pack --dry-run",
     "lint": "yarn lint:changelog",
     "lint:changelog": "auto-changelog validate --formatter oxfmt",
-    "lint:skills": "node .github/scripts/lint-skill-entry.mjs"
+    "audit:skills": "node .github/scripts/lint-skill-entry.mjs"
   },
   "publishConfig": {
     "access": "public",
diff --git a/test/lint-skill-entry.test.mjs b/test/lint-skill-entry.test.mjs
index 36852b76..bb721c01 100644
--- a/test/lint-skill-entry.test.mjs
+++ b/test/lint-skill-entry.test.mjs
@@ -73,6 +73,29 @@ describe('lint-skill-entry', () => {
     assert.match(output, /must match the directory/u);
   });
 
+  // `workflows/` was the live failure mode this audit surfaced on `main`: 14 files across
+  // two web3-tools skills, referenced 22 times, never shipped. It is now IN the bundle
+  // list, so the guarantee to test is the general one — a sibling the installer does not
+  // copy must fail, whatever it is called.
+  test('a sibling directory the installer does not ship fails', () => {
+    const root = makeRoot();
+    const dir = writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x');
+    mkdirSync(path.join(dir, 'playbooks'));
+    const { code, output } = lint(root);
+    assert.equal(code, 1, output);
+    assert.match(output, /unexpected directory "playbooks\/"/u);
+  });
+
+  test('every directory in BUNDLE_DIRS is accepted as a sibling', () => {
+    const root = makeRoot();
+    const dir = writeSkill(root, 'testing', 'unit-testing', 'name: unit-testing\ndescription: x');
+    for (const bundle of BUNDLE_DIRS) {
+      mkdirSync(path.join(dir, bundle), { recursive: true });
+    }
+    const { code, output } = lint(root);
+    assert.equal(code, 0, output);
+  });
+
   test('a knowledge/ sibling directory fails (the conversion guarantee)', () => {
     const root = makeRoot();
     const dir = writeSkill(root, 'perps', 'fix-bug', 'name: fix-bug\ndescription: x');
diff --git a/tools/skill-schema.mjs b/tools/skill-schema.mjs
index fc89c6a5..e9155740 100644
--- a/tools/skill-schema.mjs
+++ b/tools/skill-schema.mjs
@@ -10,6 +10,9 @@ export const KNOWN_FRONTMATTER = [...REQUIRED_FRONTMATTER, ...OPTIONAL_FRONTMATT
 
 export const MATURITY_VALUES = ['experimental', 'stable', 'deprecated'];
 
+// `scope: user` installs to $HOME instead of the target repo; anything else is project scope.
+export const SCOPE_VALUES = ['user', 'project'];
+
 // Directories the installer copies alongside skill.md (see tools/install).
 export const BUNDLE_DIRS = ['references', 'scripts', 'assets', 'adapters', 'workflows'];
 

From 93c4ab6a20b2f7126bbacdf43355cd7e3f9f9273 Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 16:07:24 -0400
Subject: [PATCH 6/8] Use the repo's own checkout action

Code scanning raised three findings on this workflow: `actions/checkout` and
`actions/setup-node` unpinned against the blanket hash policy, and checkout
persisting credentials.

Pinning both to SHAs would satisfy the scanner while leaving this the only
workflow here reaching for third-party actions. Every other one uses
`MetaMask/action-checkout-and-setup@v3`, which does checkout and Node setup
together; it takes `fetch-depth`, which is all this needed from raw checkout.
Switching removes the dependency, and the findings with it.
---
 .github/workflows/lint-skill-entry.yml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/lint-skill-entry.yml b/.github/workflows/lint-skill-entry.yml
index ec61349a..ea57de1a 100644
--- a/.github/workflows/lint-skill-entry.yml
+++ b/.github/workflows/lint-skill-entry.yml
@@ -16,14 +16,15 @@ jobs:
     name: Lint skill entries
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-        with:
-          # Need the base commit to diff against.
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
+      # The repo's own composite action, as every other workflow here uses. Removes the
+      # third-party dependency, and with it the unpinned-reference and credential-
+      # persistence findings that raw actions/checkout raised.
+      - uses: MetaMask/action-checkout-and-setup@v3
         with:
+          is-high-risk-environment: false
           node-version: 24.x
+          # Full history: the changed-file diff needs the base commit.
+          fetch-depth: 0
 
       # Filenames come from PR contents, so they are untrusted input. They are read
       # NUL-delimited, passed through the environment, and split on NUL into an array —

From 79b21a986546f8e77384de4d5a8addc3d75de343 Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Thu, 30 Jul 2026 16:14:56 -0400
Subject: [PATCH 7/8] Pin the checkout action to a hash
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Code scanning applies the blanket hash policy to first-party actions too, so
`MetaMask/action-checkout-and-setup@v3` still failed after the switch away from
third-party ones.

Pinned to 0543b5929698c71e3ccc6ed24eac87825669b5de (v3.5.0), with the tag in a
trailing comment so the version stays readable. The other workflows here still
float on `@v3` — they predate the check and are outside this change.
---
 .github/workflows/lint-skill-entry.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/lint-skill-entry.yml b/.github/workflows/lint-skill-entry.yml
index ea57de1a..b774aa7a 100644
--- a/.github/workflows/lint-skill-entry.yml
+++ b/.github/workflows/lint-skill-entry.yml
@@ -19,7 +19,9 @@ jobs:
       # The repo's own composite action, as every other workflow here uses. Removes the
       # third-party dependency, and with it the unpinned-reference and credential-
       # persistence findings that raw actions/checkout raised.
-      - uses: MetaMask/action-checkout-and-setup@v3
+      # Pinned to a hash per the blanket policy code scanning enforces. The other
+      # workflows here still float on @v3; they predate the policy check.
+      - uses: MetaMask/action-checkout-and-setup@0543b5929698c71e3ccc6ed24eac87825669b5de # v3.5.0
         with:
           is-high-risk-environment: false
           node-version: 24.x

From 1d216c3ff87db115c29453f62341d2a91e80d55f Mon Sep 17 00:00:00 2001
From: Jongsun Suh <jongsun.suh@icloud.com>
Date: Fri, 31 Jul 2026 03:24:29 -0400
Subject: [PATCH 8/8] Raise the description budget to 1,536 and stop calling it
 an operator limit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 1,024 ceiling was justified as the per-operator minimum, citing OpenCode.
That claim has no source and does not survive checking: `tools/install` emits
the description verbatim with no truncation anywhere, and six skills over 1,024
— up to 1,344 — install and load in Claude Code today. Nothing observed here
rejects or truncates a longer one.

It also never bound anything. The 46 skills on `main` have a median description
of 45 characters and a maximum of 928, so the limit was enforced against a
corpus that never approached it, while blocking four skills in open PRs that do.

The cost of enforcing it is real. A description is the discovery surface and the
only part of a skill carrying its own trigger cues, so trimming one to fit makes
the skill less likely to be selected when it is relevant. Cutting content to
satisfy an unverified number trades function for compliance.

Raised to 1,536, which is what README and SKILL_TEMPLATE said before they were
reconciled downward to match the constant — the reconciliation went the wrong
way. The comment now states plainly that this is a repo budget bounding
always-on context, and asks for an operator and version before anyone claims a
figure is externally imposed. The linter says "budget" rather than "operator
ceiling" for the same reason.

Restores the `performance` description to its full 1,078 characters, cut to 928
only to satisfy the old number.

Two tests keep the story straight: the boundary case derives its length from the
constant instead of hardcoding one that silently stops testing the boundary when
the budget moves, and a new check fails if README, CONTRIBUTING, or
SKILL_TEMPLATE state a number the schema does not enforce.
---
 .github/SKILL_TEMPLATE.md                     |  2 +-
 .github/scripts/lint-skill-entry.mjs          |  2 +-
 CONTRIBUTING.md                               |  2 +-
 README.md                                     |  7 ++--
 .../performance/skills/performance/skill.md   |  2 +-
 test/lint-skill-entry.test.mjs                | 33 ++++++++++++++++---
 tools/skill-schema.mjs                        | 15 ++++++---
 7 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/.github/SKILL_TEMPLATE.md b/.github/SKILL_TEMPLATE.md
index 76f8726d..0437c846 100644
--- a/.github/SKILL_TEMPLATE.md
+++ b/.github/SKILL_TEMPLATE.md
@@ -12,7 +12,7 @@ name: example-skill
 description: >-
   One or two sentences: what the skill does, plus when_to_use cues
   (e.g. "Use when asked to …, or for …"). Keep the full description
-  within 1,024 characters.
+  within 1,536 characters.
 maturity: stable
 ---
 
diff --git a/.github/scripts/lint-skill-entry.mjs b/.github/scripts/lint-skill-entry.mjs
index 780bbdc5..8de11ba1 100644
--- a/.github/scripts/lint-skill-entry.mjs
+++ b/.github/scripts/lint-skill-entry.mjs
@@ -63,7 +63,7 @@ export function lintSkill(skill) {
   if (!raw.description) {
     errors.push('missing required `description` in frontmatter');
   } else if (raw.description.length > DESCRIPTION_MAX) {
-    errors.push(`\`description\` is ${raw.description.length} chars, over the ${DESCRIPTION_MAX}-char operator ceiling`);
+    errors.push(`\`description\` is ${raw.description.length} chars, over the ${DESCRIPTION_MAX}-char budget`);
   }
 
   if (raw.maturity && !MATURITY_VALUES.includes(raw.maturity)) {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 45b7d51a..d2616a98 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -170,7 +170,7 @@ Your `skill.md` should include YAML frontmatter plus body content:
 ```yaml
 ---
 name: <slash-command-name>
-description: <≤1,024 chars including when_to_use cues>
+description: <≤1,536 chars including when_to_use cues>
 maturity: stable          # experimental | stable | deprecated
 ---
 ```
diff --git a/README.md b/README.md
index 1a4ae919..ab639f72 100644
--- a/README.md
+++ b/README.md
@@ -382,7 +382,7 @@ domains/<area>/
 ```yaml
 ---
 name: <slash-command-name>
-description: <≤1,024 chars including when_to_use cues>
+description: <≤1,536 chars including when_to_use cues>
 maturity: stable          # experimental | stable | deprecated (default stable)
 ---
 ```
@@ -391,8 +391,9 @@ Extra metadata blocks (e.g. OpenClaw-style `metadata:` with emoji and
 homepage) are preserved through install — only `name`, `description`,
 `maturity`, `mandatory`, and `scope` are read by the CLI.
 
-The 1,024-character ceiling is the lowest limit across operators, so a description
-that fits is accepted by all of them. It is enforced by `yarn audit:skills` from
+The 1,536-character ceiling is a repo budget rather than an operator limit — the
+description is always-on context for every installed skill, so it is capped
+deliberately. It is enforced by `yarn audit:skills` from
 [`tools/skill-schema.mjs`](tools/skill-schema.mjs), which is the source of truth.
 
 ### Overlay frontmatter
diff --git a/domains/performance/skills/performance/skill.md b/domains/performance/skills/performance/skill.md
index b0302e89..dafe01cc 100644
--- a/domains/performance/skills/performance/skill.md
+++ b/domains/performance/skills/performance/skill.md
@@ -1,4 +1,4 @@
 ---
 name: performance
-description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time data, frequent updates, or large lists; reviewing PRs for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; analyzing a captured `.cpuprofile` / React Native Release Profiler trace to find why a flow is slow; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, trace() instrumentation, and CPU-profile analysis. Not for correctness bugs, styling, Solidity gas, or the browser extension.
+description: Use for any performance question about the MetaMask Mobile React Native app, at any stage. Trigger when: a screen, list, or interaction feels slow, laggy, or janky (account/network switching, scrolling, typing, FPS drops); planning a feature with real-time/websocket data, frequent updates, or large lists and wanting to avoid perf pitfalls before building; reviewing or auditing PRs/code for excessive re-renders, broken selector memoization, Context providers, hook deps, or bundle bloat; making the app faster for power users with many accounts/assets; measuring time-to-interactive, render counts, or FPS and surfacing them in Sentry; analyzing a captured `.cpuprofile` / React Native Release Profiler trace (e.g. a `sampling-profiler-trace*.cpuprofile`) to find why a flow is slow; or adding render-regression tests so CI catches slowdowns. Covers re-renders, reselect memoization, FlashList, Reanimated, TTI, bundle size, trace() instrumentation, and Release Profiler CPU-profile analysis. Not for correctness bugs, styling/spacing, Solidity gas, or the browser extension.
 ---
diff --git a/test/lint-skill-entry.test.mjs b/test/lint-skill-entry.test.mjs
index bb721c01..744096ce 100644
--- a/test/lint-skill-entry.test.mjs
+++ b/test/lint-skill-entry.test.mjs
@@ -7,8 +7,8 @@ import { fileURLToPath } from 'node:url';
 import { afterEach, describe, test } from 'node:test';
 import {
   BUNDLE_DIRS,
-  KNOWN_FRONTMATTER,
   DESCRIPTION_MAX,
+  KNOWN_FRONTMATTER,
   KNOWN_KNOWLEDGE_FRONTMATTER,
 } from '../tools/skill-schema.mjs';
 
@@ -113,12 +113,14 @@ describe('lint-skill-entry', () => {
     assert.match(output, /prefix/u);
   });
 
-  test('a description over the operator ceiling fails', () => {
+  test('a description over the budget fails', () => {
     const root = makeRoot();
-    writeSkill(root, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(1100)}`);
+    // Derived from the constant: a hardcoded length silently stops testing the boundary
+    // the moment the budget moves.
+    writeSkill(root, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(DESCRIPTION_MAX + 1)}`);
     const { code, output } = lint(root);
     assert.equal(code, 1);
-    assert.match(output, /operator ceiling/u);
+    assert.match(output, /over the \d+-char budget/u);
   });
 
   test('an invalid maturity value fails', () => {
@@ -176,6 +178,27 @@ describe('schema tracks the installer', () => {
 // The workflow invokes the linter WITH changed-file arguments. Every test above runs the
 // no-argument full-audit branch, so the branch CI actually depends on had no coverage —
 // which is how malformed paths reached main. These mirror the CI invocation.
+// 1,536 is a repo budget, not an operator limit — no observed operator rejects or
+// truncates a longer description, and several over 1,024 install and load today. The
+// check exists to bound always-on context, so what matters is that the number the docs
+// state and the number enforced are the same one.
+describe('description budget', () => {
+  test('the enforced ceiling is the one the docs state', () => {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    for (const doc of ['README.md', 'CONTRIBUTING.md', path.join('.github', 'SKILL_TEMPLATE.md')]) {
+      const body = readFileSync(path.join(root, doc), 'utf8');
+      const stated = [...body.matchAll(/(\d[\d,]*)[- ]?character|≤([\d,]+) chars|within ([\d,]+) characters/gu)]
+        .flatMap((m) => [m[1], m[2], m[3]])
+        .filter(Boolean)
+        .map((n) => Number(n.replace(/,/gu, '')))
+        .filter((n) => n > 100);
+      for (const n of stated) {
+        assert.equal(n, DESCRIPTION_MAX, `${doc} states ${n} but the schema enforces ${DESCRIPTION_MAX}`);
+      }
+    }
+  });
+});
+
 describe('changed-files mode', () => {
   test('a changed skill.md is linted', () => {
     const root = makeRoot();
@@ -242,6 +265,6 @@ describe('changed-files mode', () => {
     writeSkill(overLimit, 'testing', 'unit-testing', `name: unit-testing\ndescription: ${'x'.repeat(DESCRIPTION_MAX + 1)}`);
     const { code, output } = lint(overLimit, 'domains/testing/skills/unit-testing/skill.md');
     assert.equal(code, 1, output);
-    assert.match(output, /over the \d+-char operator ceiling/u);
+    assert.match(output, /over the \d+-char budget/u);
   });
 });
diff --git a/tools/skill-schema.mjs b/tools/skill-schema.mjs
index e9155740..290b4222 100644
--- a/tools/skill-schema.mjs
+++ b/tools/skill-schema.mjs
@@ -25,11 +25,16 @@ export const ALLOWED_SIBLING_DIRS = [...BUNDLE_DIRS, 'repos'];
 
 export const KNOWN_REPOS = ['metamask-extension', 'metamask-mobile', 'core'];
 
-// The description is always loaded into the operator's discovery surface, so it
-// is the per-skill always-on cost. The ceiling is the per-operator minimum
-// (OpenCode caps description at 1024), so a description that passes here is
-// accepted by every target.
-export const DESCRIPTION_MAX = 1024;
+// The description is always loaded into the operator's discovery surface, so it is the
+// per-skill always-on cost, and the only part of a skill that carries its own trigger
+// cues — cutting it makes the skill less likely to be selected when it is relevant.
+//
+// This is a REPO BUDGET, not an operator limit. No operator observed here rejects or
+// truncates a longer one: `tools/install` emits the value verbatim, and descriptions
+// well over 1024 characters install and load in Claude Code today. Treat a lower number
+// as a deliberate budget decision, and cite the operator and version before claiming any
+// figure is externally imposed.
+export const DESCRIPTION_MAX = 1536;
 
 export const RECOMMENDED_SECTIONS = ['When To Use', 'Workflow'];