cyber-aced 0.3.0

package/skills/manage-model-runners/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: manage-model-runners
+description: "Partial Skill: invoke by name only — the ACED manage-model-runners engine — loaded in-session by the ACED manage gateway, not user-triggered."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# manage-model-runners
+
+Maintain a family of **runner agent definitions — one per model**. Each runner is a **neutral
+executor** pinned to a single model so a skill-under-test can be run as a real subagent under that
+model, giving ACED a real (not judge-simulated) signal for effectiveness and token/cost. Loaded
+in-session by the `manage` gateway; **not user-invocable**.
+
+Three operations, all **additive**: **add** the missing runners, **list** the family, **remove** only
+the runners the user explicitly names. This engine **never auto-removes** — a model missing from a
+target list is left alone (the user may run multiple harnesses, so a runner this engine did not just
+create must not be culled).
+
+Canonical files live at user-global `~/.agents/agents/model-runner-<model>.md`, with runtime symlinks
+— the exact placement + `ln -sf` procedure `define-agent` uses.
+
+## Determine the operation
+
+Read the request for the operation. If it is unclear, ask (add / list / remove).
+
+## Resolve the target model list (add)
+
+Before writing anything, resolve which models to cover, in order:
+
+1. **Explicit** — models named in the request/args.
+2. **Curated config** — `.agents/aced/models.toml`, a `models = ["opus", "sonnet", ...]` list the
+   user maintains (nothing in the environment enumerates available models, so this is the source of
+   truth when present).
+3. **Proposed default** — when neither is given, propose the known model aliases the agent-definition
+   `model:` field accepts (`opus`, `sonnet`, `haiku`) and any newer aliases the user names.
+
+**Propose and confirm — never guess.** Show the resolved list and confirm it before writing. A model
+value is whatever the runtime's agent-definition `model:` field accepts.
+
+## add — create the missing runners
+
+For each target model:
+
+- If `~/.agents/agents/model-runner-<model>.md` **already exists**, leave it untouched (add is
+  **idempotent** — no duplicate, no overwrite).
+- Otherwise write a **new runner def** (below) at the canonical path and create one runtime symlink
+  per selected runtime.
+
+Exactly **one def per model** — model is the only axis. Do not fan out over effort (see the effort
+note below).
+
+### The runner def (neutral executor)
+
+Write the canonical file. The body is **identical across the family** — only `name` and `model`
+differ:
+
+```markdown
+---
+name: model-runner-<model>
+description: >
+  Use this agent to run an ACED skill-under-test as a real subagent under the <model> model, so its
+  effectiveness and token/cost can be measured. Delegated runner — it executes the given task exactly
+  and returns the result.
+tools: *
+model: <model>
+---
+
+# model-runner-<model>
+
+You are a neutral executor pinned to the **<model>** model. Run the skill or task you are given
+**exactly as specified** — invoke the named skill, follow its steps, and return its result.
+
+## Responsibilities
+
+- Execute the given skill/task faithfully, adding no scope of your own.
+- Return exactly what the task asks for (a result, an artifact path, or a confirmation).
+
+## Out of scope
+
+- Do not reinterpret, expand, or optimize the task beyond what it states.
+- Do not choose a different model — you exist to exercise **<model>** specifically.
+```
+
+Then create the runtime symlinks (Claude Code `~/.claude/agents/<name>.md`, and Cursor / Codex if the
+user selected them) with relative `ln -sf`, and verify each resolves — as in `define-agent`.
+
+## list — report the family
+
+Scan `~/.agents/agents/` for `model-runner-*.md` and report each: the model, the canonical path, and
+any `effort:` stamp. Show nothing else.
+
+## remove — only what the user names
+
+Remove **only** the runner def(s) the user **explicitly names** (by model or path). For each:
+
+- Show the file to be deleted and **confirm before deleting** the user-global file and its symlinks.
+- **Never** remove a runner just because it is absent from a target list — this engine does no
+  reconcile-delete. If the user asks to "clean up", list the family and let them name which to remove.
+
+## Effort stamp (optional)
+
+A plain `Agent`/`Task` spawn can override a subject's `model` but **not** its `effort` (effort lives
+in the def frontmatter); a Workflow `agent()` call can pass `effort` per call. So one def per model
+serves a Workflow-based runner directly. When a **plain-spawn** runner needs a fixed effort, stamp it
+on request: add/update writes an `effort: <low|medium|high|xhigh|max>` field on the named model's def,
+still keeping exactly one def per model. Do not create model×effort defs.
+
+## Report
+
+Summarize what changed: models added (with canonical paths + symlinks), the current family (list), or
+the runners removed. Point the user at the future ACED eval-run sweep that will use these runners.

package/skills/manage-skill-dirs/README.md

@@ -0,0 +1,17 @@
+# manage-skill-dirs
+
+The concrete engine for the ACED **skill-dirs** config — the opt-in registry of extra skill-scan
+locations `improve-skill`'s validate engine scans on top of its two built-in default roots. A
+non-user-invocable skill, loaded in-session by the `manage` gateway, carrying a self-contained `.mts`
+script that lists / CRUDs / induces / previews the patterns so users never hand-edit the config file.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/manage-skill-dirs.mts`](./scripts/manage-skill-dirs.mts)
+- **Tests:** [`scripts/manage-skill-dirs.test.mts`](./scripts/manage-skill-dirs.test.mts) (`node:test`)
+
+```bash
+node scripts/manage-skill-dirs.mts --list
+node scripts/manage-skill-dirs.mts --induce plugins/aced/skills
+node scripts/manage-skill-dirs.mts --preview 'plugins/*/skills'
+node scripts/manage-skill-dirs.mts --add 'plugins/*/skills'
+```

package/skills/manage-skill-dirs/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: manage-skill-dirs
+description: "Partial Skill: invoke by name only — config-authoring/skill-dirs' curation engine for the extra skill-scan locations improve-skill's validate engine uses — loaded by the manage gateway, not triggered by users directly."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Manage Skill Dirs
+
+The concrete engine for the ACED **skill-dirs** config — the opt-in registry of **extra** skill-scan
+locations the validate engine scans on top of its two built-in default roots. It exists so a user
+curates those locations through a clean interface instead of hand-editing the config directly.
+Loaded **in-session** by the `manage` gateway; it carries a self-contained `.mts` script (the repo's
+node-≥23.6 / no-deps convention).
+
+## The config it curates
+
+A single key — `anchors = [ … ]` — a list of repo-relative directory patterns. `*` globs one
+segment; `**` globs **zero or more** segments (any depth, including zero). There is **no capture
+token**: a skill's name comes from its own directory basename, not from the pattern, so a pattern
+containing `<` or `>` is malformed. Each pattern names a directory whose **immediate children** are
+scanned for `SKILL.md`. The two default roots (the repo-root public and private agentskills-standard
+skill directories) are **implicit and always scanned** — never listed here, and never curatable.
+
+## Run an operation
+
+```bash
+node "<skill>/scripts/manage-skill-dirs.mts" [--root .] <operation>
+```
+
+| Operation | Effect |
+|---|---|
+| `--list` | list the two fixed default roots (each explained) + every custom pattern, flagged fixed/custom |
+| `--add <pattern>` | validate + append a custom pattern (creates the config if absent); refuses a fixed default root or a malformed pattern; adding an already-present pattern is a no-op |
+| `--remove <pattern>` | drop a custom pattern; a no-op (config unchanged) when the pattern is absent |
+| `--edit <old> <new>` | replace one custom pattern; refuses a malformed `<new>`; a no-op when `<old>` is absent |
+| `--induce <path>` | from a sample directory that contains skill subdirectories, offer a literal-dir candidate and a `*`-generalization of a variable segment (e.g. a plugin name); refuses a path that is not a directory under the repo |
+| `--preview <pattern>` | list the skills a candidate pattern would discover, **without** persisting it; a malformed pattern is refused, a zero-match pattern reports none |
+
+**Curate with preview.** The intended flow: take the user's sample path → `--induce` it → `--preview`
+each candidate to show the matched skills → confirm with the user → `--add` the chosen pattern. Never
+write a pattern the user has not seen the effect of.
+
+## Boundaries
+
+Writes **only** the skill-dirs config — never a skill, `spec.md`, `status`, `approval`, or a freeze;
+it is operational config, not skill content (so `manage`'s write-ownership guard holds). It does
+**not** scan or validate skills — that is `improve-skill`'s validate engine, which *reads* this
+config. This engine validates on the **write** side so a bad pattern is never persisted.
+
+When `node` is absent, an agent performs the same edits by hand: read the `anchors` array, apply the
+CRUD, validate a pattern is repo-relative with only literal / `*` / `**` segments (never `<` or `>`),
+and never write a fixed default root.

package/skills/manage-skill-dirs/scripts/manage-skill-dirs.mts

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+// manage-skill-dirs — config-authoring/skill-dirs' concrete curation engine. Declares and curates the
+// OPT-IN extra skill-dir patterns the improve-skill validate engine scans on top of its two built-in
+// default roots (skills/, .agents/skills/). It reads/writes ONLY `.agents/aced/skill-dirs.toml` —
+// never a SKILL.md, spec.md, status, approval, or freeze.
+//
+// Operations:
+//   --list                  list the two fixed default roots (each explained) + every custom pattern
+//   --add <pattern>         validate + append a custom pattern (creates the config if absent)
+//   --remove <pattern>      drop a custom pattern (no-op + unchanged when absent)
+//   --edit <old> <new>      replace one custom pattern (rejects a malformed <new>)
+//   --induce <path>         candidate patterns for a sample dir containing skill subdirectories
+//                           (literal + a * generalization of a variable segment such as a plugin name)
+//   --preview <pattern>     the SKILL.md file(s) a candidate pattern would discover, without persisting
+//
+// A pattern is a repo-relative directory pattern; `*` globs one segment, `**` globs zero or more
+// segments (any depth). There is NO capture token — a skill's name comes from its own directory
+// basename, not from the pattern, so a pattern containing `<` or `>` is malformed. Fixed default
+// roots are implicit and cannot be curated here.
+// Pure functions are exported for node:test; running the file directly drives the CLI. No deps.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const SKILL_DIRS_CONFIG = '.agents/aced/skill-dirs.toml'
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
+
+export interface SkillDirEntry {
+	pattern: string
+	kind: 'fixed' | 'custom'
+	explanation: string
+}
+
+// The two fixed default roots (agentskills-standard), always scanned by validate and never curated here.
+export const FIXED_SKILL_DIRS: SkillDirEntry[] = [
+	{ pattern: 'skills/', kind: 'fixed', explanation: 'the repo-root public skill directory (agentskills-standard)' },
+	{
+		pattern: '.agents/skills/',
+		kind: 'fixed',
+		explanation: 'the repo-root private skill directory (agentskills-standard)',
+	},
+]
+
+// ── Config read/write (a minimal TOML: the `anchors = [ … ]` string array) ──
+
+export function parseSkillDirsToml(text: string): string[] {
+	const m = /(^|\n)\s*anchors\s*=\s*\[([\s\S]*?)\]/.exec(text)
+	if (!m) return []
+	const out: string[] = []
+	for (const q of m[2].matchAll(/"([^"]*)"|'([^']*)'/g)) out.push((q[1] ?? q[2]).trim())
+	return out.filter((s) => s !== '')
+}
+
+export function readCustomSkillDirs(root: string): string[] {
+	const file = join(root, SKILL_DIRS_CONFIG)
+	if (!existsSync(file)) return []
+	try {
+		return parseSkillDirsToml(readFileSync(file, 'utf8'))
+	} catch {
+		return []
+	}
+}
+
+export function serializeSkillDirs(patterns: string[]): string {
+	if (patterns.length === 0) return 'anchors = []\n'
+	return `anchors = [\n${patterns.map((p) => `  "${p}",`).join('\n')}\n]\n`
+}
+
+function writeCustomSkillDirs(root: string, patterns: string[]): void {
+	const file = join(root, SKILL_DIRS_CONFIG)
+	mkdirSync(dirname(file), { recursive: true })
+	writeFileSync(file, serializeSkillDirs(patterns))
+}
+
+// ── Validation ──
+
+// A pattern is well-formed iff it is repo-relative (no leading slash, no `..`) and every segment is a
+// literal, `*`, or `**` (no capture token — `<` / `>` anywhere is malformed, no empty segment).
+export function isValidPattern(pattern: string): boolean {
+	const p = pattern.trim().replace(/\\/g, '/')
+	if (p === '' || p.startsWith('/') || /(^|\/)\.\.(\/|$)/.test(p)) return false
+	const segs = p.replace(/^\/+|\/+$/g, '').split('/')
+	if (segs.some((s) => s === '')) return false
+	return segs.every((s) => s === '*' || s === '**' || !/[<>]/.test(s))
+}
+
+// True when a pattern names one of the two fixed default roots (implicit, not curated).
+export function isFixedConvention(pattern: string): boolean {
+	const p = pattern
+		.trim()
+		.replace(/\\/g, '/')
+		.replace(/^\/+|\/+$/g, '')
+	return p === 'skills' || p === '.agents/skills'
+}
+
+// ── list ──
+
+export function listSkillDirs(root: string): SkillDirEntry[] {
+	const custom = readCustomSkillDirs(root).map(
+		(pattern): SkillDirEntry => ({ pattern, kind: 'custom', explanation: 'a declared extra skill-dir pattern' }),
+	)
+	return [...FIXED_SKILL_DIRS, ...custom]
+}
+
+// ── add / remove / edit ──
+
+export type CrudResult =
+	| { ok: true; changed: boolean; patterns: string[]; message: string }
+	| { ok: false; reason: string }
+
+export function addSkillDir(root: string, pattern: string): CrudResult {
+	const p = pattern.trim()
+	if (isFixedConvention(p)) return { ok: false, reason: 'that is a fixed default root — always scanned, never curated' }
+	if (!isValidPattern(p)) return { ok: false, reason: 'malformed skill-dir pattern' }
+	const current = readCustomSkillDirs(root)
+	if (current.includes(p)) return { ok: true, changed: false, patterns: current, message: 'already present' }
+	const next = [...current, p]
+	writeCustomSkillDirs(root, next)
+	return { ok: true, changed: true, patterns: next, message: `added ${p}` }
+}
+
+export function removeSkillDir(root: string, pattern: string): CrudResult {
+	const p = pattern.trim()
+	const current = readCustomSkillDirs(root)
+	if (!current.includes(p)) return { ok: true, changed: false, patterns: current, message: 'nothing was removed' }
+	const next = current.filter((a) => a !== p)
+	writeCustomSkillDirs(root, next)
+	return { ok: true, changed: true, patterns: next, message: `removed ${p}` }
+}
+
+export function editSkillDir(root: string, oldPattern: string, newPattern: string): CrudResult {
+	const oldP = oldPattern.trim()
+	const newP = newPattern.trim()
+	if (isFixedConvention(oldP)) return { ok: false, reason: 'cannot edit a fixed default root' }
+	if (!isValidPattern(newP)) return { ok: false, reason: 'malformed replacement pattern' }
+	if (isFixedConvention(newP)) return { ok: false, reason: 'replacement is a fixed default root' }
+	const current = readCustomSkillDirs(root)
+	if (!current.includes(oldP)) return { ok: false, reason: `no such custom pattern: ${oldP}` }
+	const next = current.map((a) => (a === oldP ? newP : a))
+	writeCustomSkillDirs(root, next)
+	return { ok: true, changed: true, patterns: next, message: `edited ${oldP} -> ${newP}` }
+}
+
+// ── induce ──
+
+export type InduceResult = { ok: true; candidates: string[] } | { ok: false; reason: string }
+
+// From a sample path to a directory that CONTAINS skill subdirectories, offer a literal-directory
+// candidate and a *-generalized candidate (the variable segment right before the sample dir's own
+// name — e.g. a plugin name — replaced with a *). Rejects a path that is not a directory under the
+// repo root.
+export function inducePatterns(root: string, samplePath: string): InduceResult {
+	const rel = samplePath
+		.trim()
+		.replace(/\\/g, '/')
+		.replace(/^\/+|\/+$/g, '')
+	if (rel === '' || /(^|\/)\.\.(\/|$)/.test(rel)) return { ok: false, reason: 'path is not repo-relative' }
+	let ok = false
+	try {
+		ok = statSync(join(root, rel)).isDirectory()
+	} catch {
+		ok = false
+	}
+	if (!ok) return { ok: false, reason: `sample path does not resolve to a directory under the repo: ${rel}` }
+	const segs = rel.split('/')
+	let generalized = rel
+	if (segs.length >= 2) {
+		const g = [...segs]
+		g[segs.length - 2] = '*'
+		generalized = g.join('/')
+	}
+	const candidates = generalized === rel ? [rel] : [rel, generalized]
+	return { ok: true, candidates }
+}
+
+// ── preview ──
+
+interface PreviewMatch {
+	path: string
+	name: string
+}
+
+export type PreviewResult = { ok: true; matches: PreviewMatch[] } | { ok: false; reason: string }
+
+// Every dir reachable from `startDir` by descending zero or more levels (startDir itself included),
+// skipping SKIP_DIRS. Backs the `**` segment (any-depth glob) below.
+function collectDescendants(root: string, startDir: string): string[] {
+	const out = [startDir]
+	let entries: import('node:fs').Dirent[]
+	try {
+		entries = readdirSync(join(root, startDir), { withFileTypes: true })
+	} catch {
+		return out
+	}
+	for (const e of entries) {
+		if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue
+		out.push(...collectDescendants(root, startDir ? `${startDir}/${e.name}` : e.name))
+	}
+	return out
+}
+
+// Expand a pattern against the filesystem into the set of directories it matches (mirrors the
+// improve-skill validate engine's own expansion). Does NOT read or persist anything to the config.
+function expandPattern(root: string, pattern: string): string[] {
+	const segs = pattern
+		.replace(/\\/g, '/')
+		.replace(/^\/+|\/+$/g, '')
+		.split('/')
+		.filter(Boolean)
+	let frontier: string[] = ['']
+	for (const seg of segs) {
+		const next: string[] = []
+		if (seg === '**') {
+			for (const dir of frontier) next.push(...collectDescendants(root, dir))
+			frontier = next
+			continue
+		}
+		if (seg === '*') {
+			for (const dir of frontier) {
+				let entries: import('node:fs').Dirent[]
+				try {
+					entries = readdirSync(join(root, dir), { withFileTypes: true })
+				} catch {
+					continue
+				}
+				for (const e of entries) {
+					if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue
+					next.push(dir ? `${dir}/${e.name}` : e.name)
+				}
+			}
+			frontier = next
+			continue
+		}
+		frontier = frontier.map((dir) => (dir ? `${dir}/${seg}` : seg))
+	}
+	return frontier
+}
+
+// A skill-dir pattern names a directory whose IMMEDIATE children are skill directories: preview
+// probes `<matched-dir>/*/SKILL.md`, listing the SKILL.md file(s) that pattern would add to the scan
+// — mirroring what the built-in defaults (skills/, .agents/skills/) already do.
+export function previewPattern(root: string, pattern: string): PreviewResult {
+	const p = pattern.trim()
+	if (!isValidPattern(p)) return { ok: false, reason: 'malformed candidate pattern' }
+	const matches: PreviewMatch[] = []
+	for (const matchedDir of expandPattern(root, p)) {
+		let entries: import('node:fs').Dirent[]
+		try {
+			entries = readdirSync(join(root, matchedDir), { withFileTypes: true })
+		} catch {
+			continue
+		}
+		for (const e of entries) {
+			if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue
+			const skillFile = matchedDir ? `${matchedDir}/${e.name}/SKILL.md` : `${e.name}/SKILL.md`
+			if (!existsSync(join(root, skillFile))) continue
+			matches.push({ path: skillFile, name: e.name })
+		}
+	}
+	matches.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+	return { ok: true, matches }
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const w = (s: string) => process.stdout.write(`${s}\n`)
+
+	if (argv.includes('--list')) {
+		w('Skill-dir patterns the validate engine scans (fixed default roots are always scanned):')
+		for (const a of listSkillDirs(root)) w(`  [${a.kind}] ${a.pattern} — ${a.explanation}`)
+		return 0
+	}
+	if (argv.includes('--add')) {
+		const r = addSkillDir(root, flag(argv, '--add') ?? '')
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--remove')) {
+		const r = removeSkillDir(root, flag(argv, '--remove') ?? '')
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--edit')) {
+		const i = argv.indexOf('--edit')
+		const r = editSkillDir(root, argv[i + 1] ?? '', argv[i + 2] ?? '')
+		w(r.ok ? r.message : `refused: ${r.reason}`)
+		return r.ok ? 0 : 1
+	}
+	if (argv.includes('--induce')) {
+		const r = inducePatterns(root, flag(argv, '--induce') ?? '')
+		if (!r.ok) {
+			w(`unusable: ${r.reason}`)
+			return 1
+		}
+		w('Candidate skill-dir patterns:')
+		for (const c of r.candidates) w(`  ${c}`)
+		return 0
+	}
+	if (argv.includes('--preview')) {
+		const r = previewPattern(root, flag(argv, '--preview') ?? '')
+		if (!r.ok) {
+			w(`invalid: ${r.reason}`)
+			return 1
+		}
+		if (r.matches.length === 0) {
+			w('This pattern matches no skill.')
+			return 0
+		}
+		w('This pattern would discover:')
+		for (const m of r.matches) w(`  ${m.path} (${m.name})`)
+		return 0
+	}
+
+	w('usage: manage-skill-dirs --list | --add <p> | --remove <p> | --edit <old> <new> | --induce <path> | --preview <p>')
+	return 0
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/repair-private-skills/README.md

@@ -0,0 +1,17 @@
+# repair-private-skills
+
+The concrete validate/repair engine for repo-private skill hygiene under `.agents/skills`. A
+non-user-invocable skill, loaded in-session by the ACED `manage` gateway, carrying a self-contained
+`.mts` script that flags (`validate`, read-only) or fixes (`repair`, writes) a stray symlink into the
+public `skills/` tree and a `SKILL.md` missing `metadata.internal: true`. `repair` writes/deletes only
+under `.agents/skills` — it never touches the public `skills/` tree.
+
+- **Skill contract:** [`SKILL.md`](./SKILL.md)
+- **Script:** [`scripts/repair-private-skills.mts`](./scripts/repair-private-skills.mts)
+- **Tests:** [`scripts/repair-private-skills.test.mts`](./scripts/repair-private-skills.test.mts) (`node:test`)
+
+```bash
+node scripts/repair-private-skills.mts --root . validate
+node scripts/repair-private-skills.mts --root . validate --format json
+node scripts/repair-private-skills.mts --root . repair
+```

package/skills/repair-private-skills/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: repair-private-skills
+description: "Partial Skill: invoke by name only — the ACED manage-gateway engine that validates and repairs repo-private skill hygiene — loaded in-session by the ACED manage gateway, not user-triggered."
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# repair-private-skills
+
+The concrete engine for repo-private skill hygiene under `.agents/skills`. It catches two problems
+a private skill can drift into:
+
+- a **stray symlink** whose target resolves into the public `skills/` tree (should be a real
+  repo-private directory, not a link into the public one)
+- a **SKILL.md missing `metadata.internal: true`** in its YAML frontmatter (the marker that keeps a
+  repo-private skill from leaking as a public one)
+
+A directory holding only `SKILL.local.md` / `SKILL.project.md` (no `SKILL.md`) is an
+**augmentation-only** entry and is never flagged. Loaded **in-session** by the `manage` gateway
+(Config runners / hygiene group); it carries a self-contained `.mts` script (the repo's
+node-≥23.6 / no-deps convention).
+
+## Run an operation
+
+```bash
+node "<skill>/scripts/repair-private-skills.mts" [--root .] <validate|repair> [--format json]
+```
+
+| Operation | Effect |
+|---|---|
+| `validate` | read-only; reports every issue found; **makes no filesystem changes**; exits nonzero when issues exist, 0 when clean |
+| `repair` | writes fixes — deletes a stray public-tree symlink, inserts the missing `metadata.internal: true`; exits 0 |
+| `--format json` | (either operation) emit the result as a single JSON object instead of one line per entry |
+
+Issue kinds `validate` reports: `public_skill_symlink`, `missing_skill_file`, `missing_frontmatter`,
+`missing_metadata_internal`. Action kinds `repair` records: `removed_public_symlink`,
+`updated_metadata`, `already_internal`, `local_augmentation_only`, `skipped_missing_skill`,
+`skipped_no_frontmatter`.
+
+**Curate with validate first.** The intended flow: run `validate` to see what is wrong, then run
+`repair` to fix it. `repair` is idempotent — a clean tree makes no writes.
+
+## Boundaries
+
+`validate` performs **zero filesystem writes** — it only reads and reports. `repair` writes/deletes
+**only under `.agents/skills`** — it never creates, modifies, or deletes anything under the public
+`skills/` tree, even though it reads that tree (via a resolved realpath comparison) to detect a stray
+symlink pointing into it.
+
+`repair-private-skills` does not discover skills across all sources — that is `list-skills`. It does
+not maintain the per-model runner-def family — that is `manage-model-runners`.
+
+When `node` is absent, an agent performs the same checks by hand: for each entry under
+`.agents/skills`, `lstat` it — if it is a symlink whose realpath resolves inside the public `skills/`
+tree, delete it; otherwise read `SKILL.md` (skip if absent and a `SKILL.local.md` /
+`SKILL.project.md` exists instead; flag if neither exists), skip if its first line is not `---`
+(malformed frontmatter is never auto-fixed), and insert `metadata.internal: true` under an existing
+`metadata:` block (or append a new one) when it is missing.