@csark0812/skeleton 1.5.2 → 1.5.3

package/README.md

@@ -2,17 +2,25 @@
 
 **Source of truth for** Package overview.
 
-<!-- doc-meta: owner=eng | last-reviewed=2026-07-13 -->
+<!-- doc-meta: owner=eng | last-reviewed=2026-07-15 -->
 
-Single source of truth (SSOT) linter for agent-enabled repos.
+Agent repos get messy fast. Skills get copied around, docs disagree, links go stale, and nobody remembers which file is actually canonical.
 
-Agent repos accumulate skills, rules, registries, and cross-linked docs faster than anyone can keep them straight by hand. Code repos solved this decades ago with ESLint — deterministic checks, CI gates, fix what you can before merge. Skeleton does the same job for documentation architecture: what's canonical, what links where, what must not exist, and whether your skill overrides are wired correctly.
+Skeleton is an SSOT linter for that layer. You define the contract once; Skeleton checks it locally and in CI.
 
-Skeleton is **not** a runtime agent harness. It does not execute tools, enforce permissions, or manage agent memory. It is a CLI that audits docs, skills, and registries, and fails CI when invariants break.
+If a canonical doc disappears, a registry drifts, a skill index stops matching disk, or a generated reference gets edited by hand, the audit fails before merge.
 
-## Why
+Think ESLint, but for the docs and skills your agents rely on.
 
-Code has linters. Agent repos need the same thing for docs and SSOT.
+Skeleton is **not** a runtime agent harness. It doesn't execute tools, enforce permissions, or manage memory. It checks whether the repo around those systems still holds together.
+
+## Why this matters
+
+Agents can read the repo. They can't reliably infer which of three conflicting docs wins, whether a synced skill should be edited here, or which validation command actually proves a change.
+
+That stuff needs to be explicit. More importantly, it needs to stay true after the next 50 PRs.
+
+Skeleton turns those repo conventions into checks:
 
 | Code repos                                              | Agent repos                                                                            |
 | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
@@ -20,7 +28,20 @@ Code has linters. Agent repos need the same thing for docs and SSOT.
 | `eslint --fix` on changed files                         | `skeleton validate changed` on changed docs and skills                                 |
 | Pre-commit + CI gate                                    | `--staged` pre-commit + `--base` CI gate                                               |
 
-Skill linters (skillmark, agentlint, skillscheck) answer: _"Is this SKILL.md well-formed?"_ Skeleton answers: _"Does this repo's documentation system hold together?"_
+Skill linters answer: _"Is this SKILL.md well-formed?"_
+
+Skeleton answers the repo-level question: _"Does this whole thing still agree with itself?"_
+
+## What the research says
+
+Research here is still early, but the direction is useful: more context isn't automatically better.
+
+- A [2026 study of repo-level context files](https://doi.org/10.48550/arxiv.2602.11988) tested 438 coding tasks. Human-written files improved resolution by 4% on average; generated files reduced it by 3%. Both increased inference cost by more than 20%. The recommendation was pretty direct: keep instructions minimal and include what the agent can't infer.
+- A [2025 METR randomized trial](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) found experienced open-source developers took 19% longer with early-2025 AI tools while believing they were faster.
+
+Neither study proves Skeleton improves task success. That needs a Skeleton-specific benchmark.
+
+What they do support is the constraint Skeleton is built around: keep the useful context small, make ownership clear, and verify the rest instead of trusting that it stayed correct.
 
 ## Quick start
 
@@ -29,7 +50,7 @@ npm install -D @csark0812/skeleton
 npx skeleton init --skills
 ```
 
-Init writes `.skeleton/`, merges validate scripts into `package.json`, and wires customize hooks for Cursor, Claude Code, and Codex.
+That writes `.skeleton/`, adds the validation scripts, and wires customize hooks for Cursor, Claude Code, and Codex.
 
 Edit `.skeleton/config.yaml` for your repo layout, then verify:
 
@@ -37,7 +58,7 @@ Edit `.skeleton/config.yaml` for your repo layout, then verify:
 npx skeleton audit self
 ```
 
-See [install](docs/developer/install.md) for flags and options.
+Flag details: [install](docs/developer/install.md).
 
 ## What it checks
 
@@ -50,7 +71,7 @@ See [install](docs/developer/install.md) for flags and options.
 - **Prose policy** (optional plugins) — YAML pattern rules; idle with no plugins
 - **Shell / JSON syntax** — lightweight checks on changed `.sh` and `.json` files
 
-Code validation (TypeScript, Python, Nx, pytest) stays in your repo. Skeleton handles SSOT-adjacent paths only.
+Skeleton doesn't replace your code gates. Keep TypeScript, Python, Nx, pytest, etc. in the repo that owns them.
 
 ## The `.skeleton/` contract
 
@@ -75,7 +96,7 @@ Register it:
 skeleton register docs/developer/api.md
 ```
 
-Synced toolbox skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject via IDE hooks on skill read — no editing synced `SKILL.md` files.
+Synced skills stay pristine. Project overrides live in `.skeleton/customize/<slug>.md` and inject when the skill is read. No editing copied `SKILL.md` files.
 
 ## Commands
 
@@ -91,41 +112,33 @@ skeleton customize resolve <slug>
 
 **Validate changed** routes git diffs to the right audit:
 
-| Path                                                                                | Action                      |
-| ----------------------------------------------------------------------------------- | --------------------------- |
-| Docs in scan perimeter                                                              | path-scoped audit           |
-| Skill bodies (`SKILL.md` trees)                                                     | exit 1 → run `audit skills` |
-| `.sh`, `.bash`, `.zsh`                                                              | shellcheck or `bash -n`     |
-| Other `.json`                                                                       | JSONC-tolerant syntax check |
-| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `package.json`, `project.json` | skip (exits 1 if all skip)  |
+| Path                                                                                | Action                                                        |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Docs in scan perimeter                                                              | path-scoped audit                                             |
+| Owned skill bodies (`SKILL.md` trees)                                               | exit 1 → run `audit skills`                                   |
+| Foreign / lockfile-synced skill bodies                                              | skip → lint in the owning skills/toolbox repo                 |
+| `.sh`, `.bash`, `.zsh`                                                              | shellcheck or `bash -n`                                       |
+| Other `.json`                                                                       | JSONC-tolerant syntax check                                   |
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `package.json`, `project.json` | skip (exits 1 if all skip)                                    |
 
 Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
+
 CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
 
 ## Ecosystem
 
-Skeleton is the shared validation layer in a three-tier setup:
+The model is simple:
 
-| Repo                 | Role                                               |
-| -------------------- | -------------------------------------------------- |
-| **skeleton**         | SSOT audit CLI (this repo)                         |
-| **toolbox**          | Team skills + public agent preferences             |
-| **personal-toolbox** | Private skills + personal preferences              |
-| **Consumer apps**    | Call skeleton for SSOT; keep code validation local |
+| Layer             | Role                                                                                           |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| **Skeleton**      | Defines and checks the SSOT contract                                                           |
+| **Shared skills** | Reusable team or public skills. [toolbox](https://github.com/csark0812/toolbox) is one example |
+| **Consumer apps** | Pull in the skills, run Skeleton on SSOT paths, and keep their own code gates                  |
 
-Skeleton never calls Nx or other task runners — consumers call skeleton for doc and skill paths, then handle code paths themselves.
+Skeleton never calls Nx or another app task runner. Consumer repos keep ownership of test, typecheck, and build.
 
 See [tiers](docs/tiers.md).
 
-## Distribution
-
-| Channel                                              | Installs                                                |
-| ---------------------------------------------------- | ------------------------------------------------------- |
-| `npm install -D @csark0812/skeleton`                 | CLI, schemas, audit engine, hook script                 |
-| `npx skills add csark0812/skeleton --skill skeleton` | `/skeleton` agent skill (ops manual, not the installer) |
-
-One command for humans: `npx skeleton init --skills`.
-
 ## Docs
 
 - [Install](docs/developer/install.md)
@@ -145,6 +158,8 @@ bun install
 bun run check
 ```
 
-`bun run check` runs lint, test, typecheck, build, and `audit:self`. `validate:changed` is docs/config only for path-scoped work — it skips code/config extensions (see table) and skill-body edits need `audit skills`. All-skip / skill-only / missing paths exit non-zero. Use `bun test`, `bun run typecheck`, and `bun run build` for code.
+`bun run check` = lint + test + typecheck + build + `audit:self`.
+
+`validate:changed` is docs/config only for path-scoped work — it skips code/config extensions (see table above). Owned skill-body edits need `audit skills`. All-skip, owned skill paths (alone or mixed with docs), and missing paths exit non-zero. For code: `bun test`, `bun run typecheck`, `bun run build`.
 
 Optional: `brew install pre-commit` (or `pipx install pre-commit`), then `pre-commit install` to wire `.pre-commit-config.yaml`.

package/dist/cli.js

@@ -15651,6 +15651,9 @@ var require_extend = __commonJS((exports, module) => {
   };
 });
 
+// src/cli.ts
+import { readFileSync as readFileSync22 } from "node:fs";
+
 // src/audit/config/load.ts
 var import_ajv = __toESM(require_ajv(), 1);
 import { existsSync, readFileSync } from "node:fs";
@@ -16984,12 +16987,99 @@ async function loadPlugins(root, config) {
 }
 
 // src/audit/core/collect.ts
-import { existsSync as existsSync6, readFileSync as readFileSync4, realpathSync as realpathSync4, statSync as statSync2 } from "node:fs";
-import { join as join5, relative as relative4 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync5, realpathSync as realpathSync4, statSync as statSync2 } from "node:fs";
+import { join as join6, relative as relative4 } from "node:path";
+
+// src/audit/core/skill-roots.ts
+import { existsSync as existsSync6, readdirSync as readdirSync2, readlinkSync, realpathSync as realpathSync3 } from "node:fs";
+import { join as join5, relative as relative3 } from "node:path";
+
+// src/audit/core/skill-provenance.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
+import { join as join4 } from "node:path";
+var DEFAULT_SKILLS_LOCKFILE = "skills-lock.json";
+function isForeignLockSourceType(sourceType) {
+  return sourceType !== "local";
+}
+function loadSkillsLock(root, lockfileRel = DEFAULT_SKILLS_LOCKFILE) {
+  const warnings = [];
+  const abs = join4(root, lockfileRel);
+  if (!existsSync5(abs)) {
+    return { lockfile: null, entries: {}, warnings };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync4(abs, "utf8"));
+  } catch (error) {
+    warnings.push(`malformed ${lockfileRel}: ${error instanceof Error ? error.message : String(error)}`);
+    return { lockfile: lockfileRel, entries: {}, warnings };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    warnings.push(`${lockfileRel}: expected a JSON object`);
+    return { lockfile: lockfileRel, entries: {}, warnings };
+  }
+  const obj = raw;
+  if (obj.version !== 1) {
+    warnings.push(`${lockfileRel}: unsupported version ${String(obj.version)} (expected 1); ignoring entries`);
+    return { lockfile: lockfileRel, entries: {}, warnings };
+  }
+  const skillsRaw = obj.skills;
+  if (!skillsRaw || typeof skillsRaw !== "object" || Array.isArray(skillsRaw)) {
+    warnings.push(`${lockfileRel}: missing or invalid "skills" object`);
+    return { lockfile: lockfileRel, entries: {}, warnings };
+  }
+  const entries = {};
+  for (const [slug, value] of Object.entries(skillsRaw)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      warnings.push(`${lockfileRel}: skill "${slug}" has invalid entry`);
+      continue;
+    }
+    const entry = value;
+    const source = entry.source;
+    const sourceType = entry.sourceType;
+    if (typeof source !== "string" || source.length === 0) {
+      warnings.push(`${lockfileRel}: skill "${slug}" missing source`);
+      continue;
+    }
+    if (typeof sourceType !== "string" || sourceType.length === 0) {
+      warnings.push(`${lockfileRel}: skill "${slug}" missing sourceType`);
+      continue;
+    }
+    const parsed = { source, sourceType };
+    if (typeof entry.skillPath === "string")
+      parsed.skillPath = entry.skillPath;
+    if (typeof entry.computedHash === "string")
+      parsed.computedHash = entry.computedHash;
+    entries[slug] = parsed;
+  }
+  return { lockfile: lockfileRel, entries, warnings };
+}
+function classifySkillOwnership(slug, provenance, ownership) {
+  const ownedOverrides = new Set(ownership?.ownedSlugs ?? []);
+  const foreignOverrides = new Set(ownership?.foreignSlugs ?? []);
+  if (ownedOverrides.has(slug))
+    return "owned";
+  if (foreignOverrides.has(slug))
+    return "foreign";
+  const entry = provenance.entries[slug];
+  if (entry && isForeignLockSourceType(entry.sourceType))
+    return "foreign";
+  return "owned";
+}
+function resolveOwnershipForSlugs(slugs, provenance, ownership) {
+  const ownedSlugs = [];
+  const foreignSlugs = [];
+  for (const slug of slugs) {
+    if (classifySkillOwnership(slug, provenance, ownership) === "foreign") {
+      foreignSlugs.push(slug);
+    } else {
+      ownedSlugs.push(slug);
+    }
+  }
+  return { ownedSlugs, foreignSlugs };
+}
 
 // src/audit/core/skill-roots.ts
-import { existsSync as existsSync5, readdirSync as readdirSync2, readlinkSync, realpathSync as realpathSync3 } from "node:fs";
-import { join as join4, relative as relative3 } from "node:path";
 var NESTED_SKILL_ROOTS = [".claude/skills", ".agents/skills"];
 var FLAT_SKILL_DENYLIST = new Set([
   ".git",
@@ -17018,10 +17108,10 @@ function safeRealpath(path) {
   }
 }
 function listNestedSlugs(root, relRoot) {
-  const absRoot = join4(root, relRoot);
-  if (!existsSync5(absRoot))
+  const absRoot = join5(root, relRoot);
+  if (!existsSync6(absRoot))
     return [];
-  return readdirSync2(absRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NESTED_EXCLUDED_DIRS.has(entry.name)).filter((entry) => existsSync5(join4(absRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort();
+  return readdirSync2(absRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NESTED_EXCLUDED_DIRS.has(entry.name)).filter((entry) => existsSync6(join5(absRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort();
 }
 function listFlatSlugs(root) {
   const slugs = [];
@@ -17030,7 +17120,7 @@ function listFlatSlugs(root) {
       continue;
     if (FLAT_SKILL_DENYLIST.has(entry.name))
       continue;
-    if (existsSync5(join4(root, entry.name, "SKILL.md"))) {
+    if (existsSync6(join5(root, entry.name, "SKILL.md"))) {
       slugs.push(entry.name);
     }
   }
@@ -17040,8 +17130,8 @@ function detectSkillRoots(root) {
   const roots = [];
   let claudeReal = null;
   for (const relRoot of NESTED_SKILL_ROOTS) {
-    const abs = join4(root, relRoot);
-    if (!existsSync5(abs))
+    const abs = join5(root, relRoot);
+    if (!existsSync6(abs))
       continue;
     if (relRoot === ".claude/skills") {
       claudeReal = safeRealpath(abs);
@@ -17055,11 +17145,11 @@ function detectSkillRoots(root) {
         continue;
       try {
         const link = readlinkSync(abs);
-        if (link && claudeReal && safeRealpath(join4(root, link)) === claudeReal)
+        if (link && claudeReal && safeRealpath(join5(root, link)) === claudeReal)
           continue;
       } catch {}
     }
-    if (listNestedSlugs(root, relRoot).length > 0 || existsSync5(abs)) {
+    if (listNestedSlugs(root, relRoot).length > 0 || existsSync6(abs)) {
       roots.push({ kind: "nested", relPath: relRoot });
     }
   }
@@ -17069,12 +17159,13 @@ function detectSkillRoots(root) {
   }
   return roots;
 }
-function buildSkillIndex(root) {
+function buildSkillIndex(root, ownership) {
   const roots = detectSkillRoots(root);
   const slugSet = new Set;
   const slugs = [];
+  const flatSlugs = listFlatSlugs(root);
   for (const skillRoot of roots) {
-    const rootSlugs = skillRoot.kind === "nested" ? listNestedSlugs(root, skillRoot.relPath) : listFlatSlugs(root);
+    const rootSlugs = skillRoot.kind === "nested" ? listNestedSlugs(root, skillRoot.relPath) : flatSlugs;
     for (const slug of rootSlugs) {
       if (!slugSet.has(slug)) {
         slugSet.add(slug);
@@ -17082,32 +17173,50 @@ function buildSkillIndex(root) {
       }
     }
   }
-  return { roots, slugs };
+  const lockfileRel = ownership?.lockfile ?? DEFAULT_SKILLS_LOCKFILE;
+  const provenance = loadSkillsLock(root, lockfileRel);
+  const { ownedSlugs, foreignSlugs } = resolveOwnershipForSlugs(slugs, provenance, ownership);
+  return { roots, slugs, flatSlugs, ownedSlugs, foreignSlugs, provenance };
+}
+function isForeignSkillSlug(index, slug) {
+  return index.foreignSlugs.includes(slug);
 }
 function resolveSkillPath(index, root, slug) {
   for (const skillRoot of index.roots) {
-    const candidate = skillRoot.kind === "nested" ? join4(root, skillRoot.relPath, slug, "SKILL.md") : join4(root, slug, "SKILL.md");
-    if (existsSync5(candidate)) {
+    const candidate = skillRoot.kind === "nested" ? join5(root, skillRoot.relPath, slug, "SKILL.md") : join5(root, slug, "SKILL.md");
+    if (existsSync6(candidate)) {
       return normalizeRelPath(relative3(root, candidate));
     }
   }
   return null;
 }
 function isSkillPath(relPath, index) {
+  return skillSlugForPath(relPath, index) !== null;
+}
+function skillSlugForPath(relPath, index) {
   const normalized = normalizeRelPath(relPath);
-  if (normalized.endsWith("/SKILL.md"))
-    return true;
+  const flat = new Set(index.flatSlugs);
   for (const skillRoot of index.roots) {
-    const prefix = skillRoot.kind === "nested" ? `${skillRoot.relPath}/` : "";
-    if (prefix && normalized.startsWith(prefix))
-      return true;
-    if (skillRoot.kind === "flat") {
-      const first = normalized.split("/")[0];
-      if (first && index.slugs.includes(first))
-        return true;
+    if (skillRoot.kind === "nested") {
+      const prefix = `${skillRoot.relPath}/`;
+      if (!normalized.startsWith(prefix))
+        continue;
+      const slug = normalized.slice(prefix.length).split("/")[0];
+      if (slug && index.slugs.includes(slug))
+        return slug;
+      continue;
     }
+    const first = normalized.split("/")[0];
+    if (first && flat.has(first))
+      return first;
   }
-  return false;
+  return null;
+}
+function isForeignSkillPath(relPath, index) {
+  const slug = skillSlugForPath(relPath, index);
+  if (!slug)
+    return false;
+  return isForeignSkillSlug(index, slug);
 }
 var NESTED_SKILL_SLUG_RE = /(?:^|\/)\.(?:claude|agents)\/skills\/([a-z0-9-]+)\//;
 var FLAT_SKILL_REFERENCES_RE = /(?:^|\/)([a-z0-9-]+)\/references(?:\/|$)/;
@@ -17135,18 +17244,23 @@ function slugFromPath(filePath, workspaceRoot) {
   if (!flatSlug || FLAT_SKILL_DENYLIST.has(flatSlug))
     return null;
   if (workspaceRoot) {
-    if (!existsSync5(join4(workspaceRoot, flatSlug, "SKILL.md")))
+    if (!existsSync6(join5(workspaceRoot, flatSlug, "SKILL.md")))
       return null;
   }
   return flatSlug;
 }
 function skillCollectAugments(index) {
+  const owned = new Set(index.ownedSlugs);
   const patterns = [];
   for (const skillRoot of index.roots) {
     if (skillRoot.kind === "nested") {
-      patterns.push(`${skillRoot.relPath}/**`);
+      for (const slug of index.ownedSlugs) {
+        patterns.push(`${skillRoot.relPath}/${slug}/**`);
+      }
     } else {
-      for (const slug of index.slugs) {
+      for (const slug of index.flatSlugs) {
+        if (!owned.has(slug))
+          continue;
         patterns.push(`${slug}/**`);
       }
     }
@@ -17154,12 +17268,15 @@ function skillCollectAugments(index) {
   return patterns;
 }
 function listSkillMarkdownPaths(root, index) {
+  const owned = new Set(index.ownedSlugs);
   const paths = new Set;
   for (const skillRoot of index.roots) {
     const slugs = skillRoot.kind === "nested" ? listNestedSlugs(root, skillRoot.relPath) : listFlatSlugs(root);
     for (const slug of slugs) {
-      const absDir = skillRoot.kind === "nested" ? join4(root, skillRoot.relPath, slug) : join4(root, slug);
-      if (!existsSync5(absDir))
+      if (!owned.has(slug))
+        continue;
+      const absDir = skillRoot.kind === "nested" ? join5(root, skillRoot.relPath, slug) : join5(root, slug);
+      if (!existsSync6(absDir))
         continue;
       for (const abs of globSync("**/*.{md,mdc}", {
         cwd: absDir,
@@ -17176,6 +17293,9 @@ function listSkillMarkdownPaths(root, index) {
 function listSkillSlugs(index) {
   return index.slugs;
 }
+function listOwnedSkillSlugs(index) {
+  return index.ownedSlugs;
+}
 
 // src/audit/core/collect.ts
 var MARKDOWN_GLOBS = ["**/*.md", "**/*.mdc"];
@@ -17220,7 +17340,13 @@ function collectScanFiles(config, root, skillIndex) {
   if (skillIndex) {
     includePatterns.push(...skillCollectAugments(skillIndex));
   }
-  return expandPatterns(root, includePatterns, exclude);
+  const files = expandPatterns(root, includePatterns, exclude);
+  if (!skillIndex)
+    return files;
+  return files.filter((abs) => {
+    const rel = normalizeRelPath(relative4(root, abs));
+    return !isForeignSkillPath(rel, skillIndex);
+  });
 }
 function collectBannedFiles(config, root) {
   if (config.scan.banned.length === 0)
@@ -17266,19 +17392,19 @@ function collectDocMetaPaths(config, root, registryPaths, skillIndex) {
   }
   const extras = ["docs/README.md", ".skeleton/registry.md"];
   for (const file of extras) {
-    const abs = join5(root, file);
-    if (existsSync6(abs))
+    const abs = join6(root, file);
+    if (existsSync7(abs))
       paths.push(normalizeRelPath(file));
   }
   for (const rel of registryPaths) {
     if (!rel.endsWith(".md") && !rel.endsWith(".mdc"))
       continue;
-    const abs = join5(root, rel);
-    if (existsSync6(abs))
+    const abs = join6(root, rel);
+    if (existsSync7(abs))
       paths.push(normalizeRelPath(rel));
   }
   for (const abs of collectScanFiles(config, root, skillIndex)) {
-    const content = readFileSync4(abs, "utf8");
+    const content = readFileSync5(abs, "utf8");
     if (/<!--\s*doc-meta:/.test(content)) {
       paths.push(normalizeRelPath(relative4(root, abs)));
     }
@@ -17288,7 +17414,7 @@ function collectDocMetaPaths(config, root, registryPaths, skillIndex) {
 function validateScanRoots(config, root) {
   const missing = [];
   for (const tree of extractScanRootsFromInclude(config.scan.include)) {
-    if (!existsSync6(join5(root, tree)))
+    if (!existsSync7(join6(root, tree)))
       missing.push(tree);
   }
   return missing;
@@ -17310,8 +17436,8 @@ function includeExplicitMarkdownPaths(files, paths, root) {
   const out = new Set(files);
   for (const raw of paths) {
     const rel = normalizeRelPath(raw);
-    const abs = join5(root, rel);
-    if (!existsSync6(abs))
+    const abs = join6(root, rel);
+    if (!existsSync7(abs))
       continue;
     if (isMarkdownFile(rel)) {
       out.add(abs);
@@ -17335,23 +17461,23 @@ function includeExplicitMarkdownPaths(files, paths, root) {
   return [...out];
 }
 function readFileContent(absPath) {
-  return readFileSync4(absPath, "utf8");
+  return readFileSync5(absPath, "utf8");
 }
 function relPath(absPath, root) {
   return normalizeRelPath(relative4(root, absPath));
 }
 
 // src/audit/core/registry.ts
-import { existsSync as existsSync7, readFileSync as readFileSync5 } from "node:fs";
-import { join as join6, relative as relative5, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
+import { join as join7, relative as relative5, resolve as resolve4 } from "node:path";
 var REGISTRY_TABLE_ROW_RE = /^\|\s*[^|]+\|\s*\[[^\]]*\]\(([^)]+)\)\s*\|/;
 var REGISTRY_TABLE_HEADER_RE = /\|\s*Topic\s*\|\s*Canonical file\s*\|/i;
 function parseRegistry(root) {
-  const abs = join6(root, REGISTRY_REL_PATH);
-  if (!existsSync7(abs)) {
+  const abs = join7(root, REGISTRY_REL_PATH);
+  if (!existsSync8(abs)) {
     return { paths: [], hasTableHeader: false };
   }
-  const content = readFileSync5(abs, "utf8");
+  const content = readFileSync6(abs, "utf8");
   const hasTableHeader = REGISTRY_TABLE_HEADER_RE.test(content);
   const paths = [];
   for (const line of content.split(`
@@ -17362,7 +17488,7 @@ function parseRegistry(root) {
     const linkTarget = match[1].trim();
     if (linkTarget.startsWith("#"))
       continue;
-    const resolved = resolve4(join6(root, REGISTRY_DIR_REL), linkTarget);
+    const resolved = resolve4(join7(root, REGISTRY_DIR_REL), linkTarget);
     paths.push(normalizeRelPath(relative5(root, resolved)));
   }
   return { paths: [...new Set(paths)], hasTableHeader };
@@ -17371,27 +17497,11 @@ function parseRegistryPaths(root) {
   return parseRegistry(root).paths;
 }
 
-// src/audit/core/skills-lock.ts
-import { existsSync as existsSync8, readFileSync as readFileSync6 } from "node:fs";
-import { join as join7 } from "node:path";
-var SKILLS_LOCK_REL = "skills-lock.json";
-function lockedSkillSlugs(root) {
-  const abs = join7(root, SKILLS_LOCK_REL);
-  if (!existsSync8(abs))
-    return new Set;
-  try {
-    const parsed = JSON.parse(readFileSync6(abs, "utf8"));
-    return new Set(Object.keys(parsed.skills ?? {}));
-  } catch {
-    return new Set;
-  }
-}
-
 // src/audit/core/context.ts
 function createContext(options = {}) {
   const root = options.root ?? findRepoRoot();
   const config = loadConfig(root);
-  const skillIndex = buildSkillIndex(root);
+  const skillIndex = buildSkillIndex(root, config.skillOwnership);
   let files = collectScanFiles(config, root, skillIndex);
   if (options.includeExcludedSkillTrees) {
     files = includeExplicitMarkdownPaths(files, listSkillMarkdownPaths(root, skillIndex), root);
@@ -17411,7 +17521,7 @@ function createContext(options = {}) {
     registryHasTableHeader: registry.hasTableHeader,
     retiredSkills: new Set(retiredSkills(config)),
     skillIndex,
-    lockedSkillSlugs: lockedSkillSlugs(root),
+    lockedSkillSlugs: new Set(skillIndex.foreignSlugs),
     policies: options.policies ?? []
   };
 }
@@ -29325,10 +29435,10 @@ function findLocalCanonicalLinks(root2, content3, sourceFile) {
   }
   return links;
 }
-function discoverSkillReferencePlans(root2) {
-  const index2 = buildSkillIndex(root2);
+function discoverSkillReferencePlans(root2, ownership) {
+  const index2 = buildSkillIndex(root2, ownership);
   const plans = [];
-  for (const slug2 of index2.slugs) {
+  for (const slug2 of index2.ownedSlugs) {
     const skillDir = join10(root2, slug2);
     if (!existsSync12(join10(skillDir, "SKILL.md")))
       continue;
@@ -29419,12 +29529,13 @@ function listAllGeneratedFiles(root2) {
   walk(root2);
   return files;
 }
-function runGeneratedReferencesCheck(root2) {
+function runGeneratedReferencesCheck(root2, ownership) {
   const issues = [];
   const canonicalDir = join11(root2, CANONICAL_REFS_DIR);
   if (!existsSync13(canonicalDir))
     return issues;
-  const plans = discoverSkillReferencePlans(root2);
+  const skillIndex = buildSkillIndex(root2, ownership);
+  const plans = discoverSkillReferencePlans(root2, ownership);
   const needed = new Set;
   for (const plan of plans) {
     for (const refPath of plan.refPaths) {
@@ -29455,6 +29566,8 @@ function runGeneratedReferencesCheck(root2) {
     }
   }
   for (const generatedRel of listAllGeneratedFiles(root2)) {
+    if (isForeignSkillPath(generatedRel, skillIndex))
+      continue;
     if (!needed.has(generatedRel)) {
       issues.push(issue("generated-references", generatedRel, "orphaned generated copy — run skeleton references sync"));
     }
@@ -29486,7 +29599,7 @@ function runGeneratedReferencesCheck(root2) {
   return issues;
 }
 function runGeneratedReferencesRule(ctx) {
-  return runGeneratedReferencesCheck(ctx.root);
+  return runGeneratedReferencesCheck(ctx.root, ctx.config.skillOwnership);
 }
 var generatedReferencesRule = {
   id: "generated-references",
@@ -29801,7 +29914,8 @@ function validateReadmeTaxonomy(ctx, index2, diskSlugs) {
       continue;
     const taxonomySlugs = parseReadmeTaxonomySlugs(readme);
     const nestedSlugs = diskSlugs.filter((slug2) => existsSync17(join14(ctx.root, skillRoot.relPath, slug2, "SKILL.md")));
-    const publicSlugs = nestedSlugs.filter((slug2) => !nonPublic.has(slug2));
+    const foreign = new Set(index2.foreignSlugs);
+    const publicSlugs = nestedSlugs.filter((slug2) => !nonPublic.has(slug2) && !foreign.has(slug2));
     const relReadme = `${skillRoot.relPath}/README.md`;
     for (const slug2 of publicSlugs) {
       if (!taxonomySlugs.includes(slug2)) {
@@ -29820,30 +29934,45 @@ function runSkillIndexRule(ctx) {
   const issues = [];
   const index2 = ctx.skillIndex;
   const diskSlugs = listSkillSlugs(index2);
+  for (const warning of index2.provenance.warnings) {
+    issues.push(issue("skill-index", index2.provenance.lockfile ?? "skills-lock.json", `skill provenance: ${warning}`, {
+      severity: "warning"
+    }));
+  }
   issues.push(...validateReadmeTaxonomy(ctx, index2, diskSlugs));
+  const owned = new Set(index2.ownedSlugs);
   for (const skillRoot of index2.roots) {
-    const scanRoot = skillRoot.kind === "nested" ? join14(ctx.root, skillRoot.relPath) : join14(ctx.root);
-    if (skillRoot.kind === "nested" && existsSync17(scanRoot)) {
-      for (const skillMd of walkSkillMarkdown(scanRoot)) {
-        issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
+    if (skillRoot.kind === "nested") {
+      for (const slug2 of index2.ownedSlugs) {
+        const skillDir = join14(ctx.root, skillRoot.relPath, slug2);
+        if (!existsSync17(skillDir))
+          continue;
+        for (const skillMd of walkSkillMarkdown(skillDir)) {
+          issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
+        }
       }
+      continue;
     }
-    if (skillRoot.kind === "flat") {
-      for (const slug2 of index2.slugs) {
-        const skillDir = join14(ctx.root, slug2);
-        if (existsSync17(skillDir)) {
-          for (const skillMd of walkSkillMarkdown(skillDir)) {
-            issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
-          }
-        }
+    for (const slug2 of index2.flatSlugs) {
+      if (!owned.has(slug2))
+        continue;
+      const skillDir = join14(ctx.root, slug2);
+      if (!existsSync17(skillDir))
+        continue;
+      for (const skillMd of walkSkillMarkdown(skillDir)) {
+        issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
       }
     }
   }
   return issues;
 }
 var skillIndexRule = { id: "skill-index", run: runSkillIndexRule };
-function skillCountOnDisk(ctx) {
-  return listSkillSlugs(ctx.skillIndex).length;
+function skillAuditSuffix(ctx) {
+  const owned = listOwnedSkillSlugs(ctx.skillIndex).length;
+  const foreign = ctx.skillIndex.foreignSlugs.length;
+  if (foreign === 0)
+    return ` (${owned} skills on disk)`;
+  return ` (${owned} owned skills audited, ${foreign} foreign ignored)`;
 }
 
 // src/audit/rules/index.ts
@@ -30012,7 +30141,7 @@ async function runAudit(options) {
     json: options.json,
     label,
     fileCount: options.suite === "docs" || options.suite === "self" ? ctx.files.length : undefined,
-    successSuffix: options.suite === "skills" ? ` (${skillCountOnDisk(ctx)} skills on disk)` : undefined
+    successSuffix: options.suite === "skills" ? skillAuditSuffix(ctx) : undefined
   });
 }
 
@@ -30111,6 +30240,88 @@ function resolveCustomizeFromRoot(slug2, startDir) {
   return resolveCustomize(root2, slug2);
 }
 
+// src/hooks/run.ts
+function parsePayload(raw) {
+  if (!raw.trim())
+    return {};
+  return JSON.parse(raw);
+}
+function extractPath(payload) {
+  const input = payload.tool_input ?? payload.toolInput ?? {};
+  const candidates = [
+    input.path,
+    input.file_path,
+    input.filePath,
+    input.target_file,
+    input.targetFile
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim())
+      return normalizeRelPath(value.trim());
+  }
+  return null;
+}
+function extractSkillSlug(payload) {
+  const tool = payload.tool_name ?? payload.toolName ?? "";
+  if (tool === "Skill" || tool === "skill") {
+    const input = payload.tool_input ?? payload.toolInput ?? {};
+    const slug2 = input.skill ?? input.slug ?? input.name;
+    if (typeof slug2 === "string" && slug2.trim())
+      return slug2.trim();
+  }
+  const path2 = extractPath(payload);
+  if (path2)
+    return slugFromPath(path2, process.cwd());
+  return null;
+}
+function cursorResponse(content3) {
+  return JSON.stringify({ additional_context: content3 });
+}
+function claudeResponse(content3) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      additionalContext: content3
+    }
+  });
+}
+function codexResponse(content3) {
+  return JSON.stringify({ additionalContext: content3 });
+}
+function formatResponse(payload, content3) {
+  const tool = payload.tool_name ?? payload.toolName ?? "";
+  if (tool === "read_file")
+    return codexResponse(content3);
+  if (payload.hook_event_name?.toLowerCase().includes("claude"))
+    return claudeResponse(content3);
+  if (tool === "Read" && payload.hook_event_name === "postToolUse")
+    return cursorResponse(content3);
+  if (tool === "Read" || tool === "Skill")
+    return claudeResponse(content3);
+  return cursorResponse(content3);
+}
+function runCustomizeHook(raw) {
+  try {
+    const payload = parsePayload(raw);
+    const slug2 = extractSkillSlug(payload);
+    if (!slug2)
+      return "{}";
+    const resolved = resolveCustomizeFromRoot(slug2);
+    if (!resolved.content)
+      return "{}";
+    const from = resolved.included.length > 0 ? resolved.included.join(", ") : resolved.path ?? ".skeleton/customize";
+    const prefix = `
+
+---
+Customize override for /${slug2} (from ${from}):
+
+`;
+    return formatResponse(payload, prefix + resolved.content);
+  } catch (error) {
+    console.error(`customize hook error: ${error}`);
+    return "{}";
+  }
+}
+
 // src/init/init.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { copyFileSync, existsSync as existsSync22, mkdirSync as mkdirSync2, readFileSync as readFileSync17 } from "node:fs";
@@ -30142,29 +30353,37 @@ function resolveTemplatesDir() {
 }
 
 // src/init/resolve-hook-command.ts
-import { existsSync as existsSync20 } from "node:fs";
+import { existsSync as existsSync20, realpathSync as realpathSync6 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
 import { dirname as dirname9, join as join17, relative as relative10, resolve as resolve8 } from "node:path";
 var PACKAGE_NAME = "@csark0812/skeleton";
-var HOOK_DIST = "dist/hooks/customize-on-skill-read.js";
-var HOOK_SRC = "src/hooks/customize-on-skill-read.ts";
+var CLI_DIST = "dist/cli.js";
 var PACKAGE_ROOT = resolvePackageRoot();
+var DEV_HOOK_COMMAND = "bun src/cli.ts hook customize";
+var FALLBACK_HOOK_COMMAND = `node node_modules/${PACKAGE_NAME}/${CLI_DIST} hook customize`;
+function safeRealpath2(path2) {
+  try {
+    return realpathSync6(path2);
+  } catch {
+    return path2;
+  }
+}
 function toRepoRelative(cwd, absPath) {
-  const rel = relative10(cwd, absPath).replace(/\\/g, "/");
+  const rel = relative10(safeRealpath2(cwd), safeRealpath2(absPath)).replace(/\\/g, "/");
   return rel.startsWith("..") ? absPath.replace(/\\/g, "/") : rel;
 }
-function tryResolvePublished(cwd) {
+function tryResolvePublishedCli(cwd) {
   try {
     const req = createRequire3(join17(cwd, "package.json"));
-    return req.resolve(`${PACKAGE_NAME}/${HOOK_DIST}`);
+    return req.resolve(`${PACKAGE_NAME}/${CLI_DIST}`);
   } catch {
     return null;
   }
 }
-function walkNodeModules(cwd) {
+function walkNodeModulesCli(cwd) {
   let dir = cwd;
   while (true) {
-    const candidate = join17(dir, "node_modules", PACKAGE_NAME, HOOK_DIST);
+    const candidate = join17(dir, "node_modules", PACKAGE_NAME, CLI_DIST);
     if (existsSync20(candidate))
       return candidate;
     const parent = dirname9(dir);
@@ -30178,28 +30397,25 @@ function isInsidePackageRoot(cwd) {
   const rel = relative10(PACKAGE_ROOT, resolve8(cwd)).replace(/\\/g, "/");
   return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
 }
+function nodeCliHookCommand(cliPath) {
+  return `node ${cliPath} hook customize`;
+}
 function resolveHookCommand(cwd) {
-  const published = tryResolvePublished(cwd);
+  if (isInsidePackageRoot(cwd))
+    return DEV_HOOK_COMMAND;
+  const published = tryResolvePublishedCli(cwd);
   if (published)
-    return toRepoRelative(cwd, published);
-  const hoisted = walkNodeModules(cwd);
+    return nodeCliHookCommand(toRepoRelative(cwd, published));
+  const hoisted = walkNodeModulesCli(cwd);
   if (hoisted)
-    return toRepoRelative(cwd, hoisted);
-  if (isInsidePackageRoot(cwd)) {
-    const distHook = join17(PACKAGE_ROOT, HOOK_DIST);
-    if (existsSync20(distHook))
-      return toRepoRelative(cwd, distHook);
-    const srcHook = join17(PACKAGE_ROOT, HOOK_SRC);
-    if (existsSync20(srcHook)) {
-      const rel = toRepoRelative(cwd, srcHook);
-      return rel.includes("/") ? `bun ${rel}` : `bun ./${rel}`;
-    }
-  }
-  return `node node_modules/${PACKAGE_NAME}/${HOOK_DIST}`;
+    return nodeCliHookCommand(toRepoRelative(cwd, hoisted));
+  return FALLBACK_HOOK_COMMAND;
 }
 function isSkeletonHookCommand(command) {
   if (!command)
     return false;
+  if (/\bhook\s+customize\b/.test(command))
+    return true;
   return /customize-on-skill-read\.(js|ts)\b/.test(command);
 }
 
@@ -30646,6 +30862,15 @@ import {
   writeFileSync as writeFileSync4
 } from "node:fs";
 import { dirname as dirname12, join as join20, relative as relative11 } from "node:path";
+function resolveOwnership(root2, override) {
+  if (override !== undefined)
+    return override;
+  try {
+    return loadConfig(root2).skillOwnership;
+  } catch {
+    return;
+  }
+}
 function walkMarkdownFiles2(dir, root2) {
   const files = [];
   if (!existsSync24(dir))
@@ -30700,7 +30925,7 @@ function syncReferences(options = {}) {
     removed: [],
     skipped: []
   };
-  const plans = discoverSkillReferencePlans(root2);
+  const plans = discoverSkillReferencePlans(root2, resolveOwnership(root2, options.ownership));
   for (const plan of plans) {
     const skillDir = join20(root2, plan.skill);
     for (const refPath of plan.refPaths) {
@@ -30756,7 +30981,13 @@ function runReferencesSync(options = {}) {
 }
 function runReferencesCheck(options = {}) {
   const root2 = options.root ?? process.cwd();
-  const issues = runGeneratedReferencesCheck(root2);
+  let ownership;
+  try {
+    ownership = loadConfig(root2).skillOwnership;
+  } catch {
+    ownership = undefined;
+  }
+  const issues = runGeneratedReferencesCheck(root2, ownership);
   return printReport(issues, {
     strict: options.strict,
     json: options.json,
@@ -30823,7 +31054,7 @@ function pathFromRegistryLink(root2, link2) {
 }
 function isOutsideScan(root2, relPath2) {
   const config = loadConfig(root2);
-  const skillIndex = buildSkillIndex(root2);
+  const skillIndex = buildSkillIndex(root2, config.skillOwnership);
   const scanned = collectScanFiles(config, root2, skillIndex).map((abs) => normalizeRelPath(relative12(root2, abs)));
   if (scanned.includes(relPath2))
     return false;
@@ -30976,7 +31207,7 @@ function isSkeletonYamlCandidate(normalized, ext) {
     return false;
   return true;
 }
-function bucketFor(relPath2, root2, wiredPolicies) {
+function bucketFor(relPath2, root2, wiredPolicies, skillIndex) {
   const normalized = normalizeRelPath(relPath2);
   const ext = extname2(normalized).toLowerCase();
   const name = basename5(normalized);
@@ -30989,9 +31220,11 @@ function bucketFor(relPath2, root2, wiredPolicies) {
       return "policy";
     return "skip";
   }
-  const skillIndex = buildSkillIndex(root2);
-  if (isSkillPath(normalized, skillIndex))
+  if (isSkillPath(normalized, skillIndex)) {
+    if (isForeignSkillPath(normalized, skillIndex))
+      return "foreign-skill";
     return "skills";
+  }
   if (DOC_EXTENSIONS.has(ext)) {
     const config = loadConfig(root2);
     if (isInScanPerimeter(normalized, config, root2, skillIndex))
@@ -31102,6 +31335,7 @@ async function runValidateChanged(options = {}) {
     return 0;
   }
   const config = loadConfig(root2);
+  const skillIndex = buildSkillIndex(root2, config.skillOwnership);
   let wiredPolicies;
   try {
     wiredPolicies = await collectWiredPolicyRelPaths(root2, config);
@@ -31118,6 +31352,7 @@ async function runValidateChanged(options = {}) {
   };
   let missing = 0;
   let skipped = 0;
+  let foreignSkipped = 0;
   const orphans = [];
   for (const relPath2 of relPaths) {
     const normalized = normalizeRelPath(relPath2);
@@ -31132,11 +31367,16 @@ async function runValidateChanged(options = {}) {
       orphans.push(normalized);
       continue;
     }
-    const bucket = bucketFor(normalized, root2, wiredPolicies);
+    const bucket = bucketFor(normalized, root2, wiredPolicies, skillIndex);
     if (bucket === "skip") {
       skipped++;
       continue;
     }
+    if (bucket === "foreign-skill") {
+      foreignSkipped++;
+      console.log(`validate changed: skipping foreign skill ${normalized} (owned upstream; see skills-lock.json / skillOwnership)`);
+      continue;
+    }
     buckets[bucket].push(normalized);
   }
   if (orphans.length > 0) {
@@ -31184,24 +31424,24 @@ async function runValidateChanged(options = {}) {
       exitCode = 1;
   }
   if (buckets.skills.length > 0) {
-    const skillsOnly = buckets.docs.length === 0 && buckets.shell.length === 0 && buckets.json.length === 0 && buckets.policy.length === 0;
-    if (skillsOnly && !options.base) {
+    if (!options.base) {
       console.error(`validate changed: skill paths need the full skills suite (path-scoped skill rules are empty).
 ` + `  Run: skeleton audit skills
 ` + "  (audit self covers docs + .skeleton; excluded skill trees still need audit skills)");
-      return 1;
-    }
-    const skillExit = await runAudit({
-      suite: "skills",
-      strict: false,
-      json: false,
-      paths: buckets.skills,
-      only: null,
-      root: root2,
-      pathScopedOnly: true
-    });
-    if (skillExit !== 0)
       exitCode = 1;
+    } else {
+      const skillExit = await runAudit({
+        suite: "skills",
+        strict: false,
+        json: false,
+        paths: buckets.skills,
+        only: null,
+        root: root2,
+        pathScopedOnly: true
+      });
+      if (skillExit !== 0)
+        exitCode = 1;
+    }
   }
   for (const relPath2 of buckets.shell) {
     if (validateShell(relPath2, root2) !== 0)
@@ -31227,7 +31467,7 @@ async function runValidateChanged(options = {}) {
       });
       if (proseExit !== 0)
         exitCode = 1;
-      const skillPaths = listSkillMarkdownPaths(root2, buildSkillIndex(root2));
+      const skillPaths = listSkillMarkdownPaths(root2, skillIndex);
       if (skillPaths.length > 0) {
         const skillProseExit = await runAudit({
           suite: "skills",
@@ -31242,17 +31482,20 @@ async function runValidateChanged(options = {}) {
           exitCode = 1;
       }
     } else {
-      if (exitCode === 0) {
-        console.error(`validate changed: policy YAML changes need a full prose-policy pass (path-scoped docs are not enough).
+      console.error(`validate changed: policy YAML changes need a full prose-policy pass (path-scoped docs are not enough).
 ` + `  Run: skeleton audit docs
 ` + `  And: skeleton audit skills
 ` + "  (audit self covers docs + .skeleton; excluded skill trees still need audit skills)");
-      }
       return 1;
     }
   }
   if (exitCode === 0) {
-    const note = skipped > 0 ? ` (${skipped} path(s) skipped)` : "";
+    const parts = [];
+    if (skipped > 0)
+      parts.push(`${skipped} path(s) skipped`);
+    if (foreignSkipped > 0)
+      parts.push(`${foreignSkipped} foreign skill(s) ignored`);
+    const note = parts.length > 0 ? ` (${parts.join(", ")})` : "";
     console.log(`validate changed passed${note}.`);
   }
   return exitCode;
@@ -31270,6 +31513,7 @@ Commands:
   validate changed [paths…] [--staged] [--base <ref>]
   register <path> [--topic=…] [--dry-run] [--json]
   customize resolve <slug> [--json]
+  hook customize            (reads a host hook payload on stdin)
   references sync [--dry-run] [--no-rewrite-links]
   references check [--json] [--strict]`);
 }
@@ -31366,6 +31610,14 @@ async function main() {
       }
       process.exit(0);
     }
+    if (command === "hook") {
+      if (argv[1] !== "customize") {
+        usage();
+        process.exit(1);
+      }
+      process.stdout.write(runCustomizeHook(readFileSync22(0, "utf8")));
+      process.exit(0);
+    }
     if (command === "init") {
       const parsed = parseInitArgs(argv.slice(1));
       runInit(parsed);

package/dist/hooks/customize-on-skill-read.js

@@ -13552,7 +13552,7 @@ function resolveCustomizeFromRoot(slug, startDir) {
   return resolveCustomize(root, slug);
 }
 
-// src/hooks/customize-on-skill-read.ts
+// src/hooks/run.ts
 function parsePayload(raw) {
   if (!raw.trim())
     return {};
@@ -13611,20 +13611,15 @@ function formatResponse(payload, content) {
     return claudeResponse(content);
   return cursorResponse(content);
 }
-function main() {
+function runCustomizeHook(raw) {
   try {
-    const raw = readFileSync4(0, "utf8");
     const payload = parsePayload(raw);
     const slug = extractSkillSlug(payload);
-    if (!slug) {
-      process.stdout.write("{}");
-      return;
-    }
+    if (!slug)
+      return "{}";
     const resolved = resolveCustomizeFromRoot(slug);
-    if (!resolved.content) {
-      process.stdout.write("{}");
-      return;
-    }
+    if (!resolved.content)
+      return "{}";
     const from = resolved.included.length > 0 ? resolved.included.join(", ") : resolved.path ?? ".skeleton/customize";
     const prefix = `
 
@@ -13632,10 +13627,12 @@ function main() {
 Customize override for /${slug} (from ${from}):
 
 `;
-    process.stdout.write(formatResponse(payload, prefix + resolved.content));
+    return formatResponse(payload, prefix + resolved.content);
   } catch (error) {
     console.error(`customize hook error: ${error}`);
-    process.stdout.write("{}");
+    return "{}";
   }
 }
-main();
+
+// src/hooks/customize-on-skill-read.ts
+process.stdout.write(runCustomizeHook(readFileSync4(0, "utf8")));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@csark0812/skeleton",
-	"version": "1.5.2",
+	"version": "1.5.3",
 	"description": "SSOT audit CLI for agent harness repos",
 	"type": "module",
 	"bin": {

package/schemas/config.schema.json

@@ -55,6 +55,28 @@
 				}
 			}
 		},
+		"skillOwnership": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Provenance-aware skill body linting: foreign (synced) skills are skipped; owned local skills and .skeleton/customize stay audited",
+			"properties": {
+				"lockfile": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Repo-relative skills lock path (default: skills-lock.json)"
+				},
+				"ownedSlugs": {
+					"type": "array",
+					"items": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+					"description": "Force these skill slugs to be treated as owned (lint here) even when the lockfile marks them foreign"
+				},
+				"foreignSlugs": {
+					"type": "array",
+					"items": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+					"description": "Force these skill slugs to be treated as foreign (skip body lint) even when absent from the lockfile"
+				}
+			}
+		},
 		"plugins": {
 			"type": "array",
 			"items": { "type": "string", "minLength": 1 },

package/templates/skeleton-init/config.yaml

@@ -18,6 +18,12 @@ daysUntilStale: 180
 #   alwaysInclude:
 #     - shared-agent-references.md
 
+# Optional: skill body ownership (skills-lock.json github entries are foreign by default)
+# skillOwnership:
+#   lockfile: skills-lock.json
+#   ownedSlugs: []
+#   foreignSlugs: []
+
 # Optional: plugin `.ts` entries relative to .skeleton/ (built sibling `.mjs` required)
 # plugins: []
 # Optional: draft-marker allow-list prefixes (plus `_draft-*.md` filenames)