@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-hooks/src/hooks/user-prompt-submit/index.ts

@@ -0,0 +1,203 @@
+/**
+ * UserPromptSubmit hook engine: BM25 (+ optional hybrid vector) skill
+ * matching over SKILL.md frontmatter, rendered as advisory context for the
+ * invoking host.
+ *
+ * Ported from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/index.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/user-prompt-submit.mjs` in enact-m5 — see
+ * that module's header and `src/match.mjs` for the ranking rationale).
+ *
+ * Adaptation from the reference: the reference's `handleUserPromptSubmit`
+ * hardcoded its skill-catalog roots from the module-level `SKILL_ROOTS`
+ * constant. `adl hook` resolves the skill directory per repository from
+ * `adl-config.toml`'s `[hooks] skills_dir` (see
+ * `../../gating/config.ts`), which `handler.ts` — not this module — is
+ * responsible for reading. So the top-level export here,
+ * `runUserPromptSubmit`, takes the resolved skill roots as a parameter
+ * instead of importing a fixed list; `handler.ts` is the thin adapter that
+ * resolves those roots and exposes the fixed `handleUserPromptSubmit`
+ * `HookHandler` shape `main.ts` dispatches to.
+ *
+ * This hook must never block a prompt: on any failure it exits 1 (never 2)
+ * with a stderr message, and always an empty stdout.
+ */
+import type { HookInvocation, HookResult } from '../contract.ts'
+import { buildMatchConfig } from './config.ts'
+import { DISABLE_ENV, MIN_PROMPT_CHARS, modelArtifactCorruptNote, modelDirMissingNote, modelLoadErrorNote } from './constants.ts'
+import { matchPrompt, renderMatches, stripOwnEcho } from './match.ts'
+import { scanSkills } from './skills.ts'
+import { loadTokenizer } from './tokenizer.ts'
+import { loadVectorHalf, resolveGlobalArtifactDir, type VectorHalf } from './vector.ts'
+import { existsSync } from 'node:fs'
+
+/**
+ * Hosts this hook renders advisory context for.
+ *
+ *  - claude / codex / cursor / opencode: `hookSpecificOutput.additionalContext`
+ *    JSON, per each host's documented UserPromptSubmit hook output contract.
+ *    OpenCode is included here (work item C) because the adl-extensions
+ *    `chat.message` plugin method it generates (`packages/agent-skills/src/create/opencode.ts`'s
+ *    `emitChatMessageMethod`/`extractHookContext`) reads exactly this same
+ *    shape from a command's stdout — preferring
+ *    `hookSpecificOutput.additionalContext`, falling back to raw trimmed
+ *    stdout otherwise — and injects it into the model's context via
+ *    `experimental.chat.system.transform` for the matching session. No
+ *    OpenCode-specific rendering was needed: it consumes the identical JSON
+ *    claude/codex/cursor already produce.
+ *  - kimi: bare text on stdout (Kimi has no structured hook-output channel).
+ *  - vscode (and any future HostId): not a UserPromptSubmit host for this
+ *    tool — exit 0, empty stdout, no-op. VS Code is audit-only and this tool
+ *    deploys nothing to it.
+ */
+const KIMI_HOST = 'kimi'
+const JSON_CONTEXT_HOSTS: ReadonlySet<string> = new Set(['claude', 'codex', 'cursor', 'opencode'])
+
+function ok(stdout: string, stderr = ''): HookResult {
+  return { stdout, stderr, exitCode: 0 }
+}
+
+function fail(message: string): HookResult {
+  return { stdout: '', stderr: `${message}\n`, exitCode: 1 }
+}
+
+/**
+ * `prompt` is the field across Claude/Codex/Kimi/Cursor today; the fallback
+ * keeps the hook working if a host renames it.
+ */
+function readPrompt(payload: Record<string, unknown>): string {
+  const prompt = payload.prompt
+  if (typeof prompt === 'string') return prompt
+  const userPrompt = payload.user_prompt
+  return typeof userPrompt === 'string' ? userPrompt : ''
+}
+
+/**
+ * Only ever called with a host `runUserPromptSubmit` has already gated to
+ * `JSON_CONTEXT_HOSTS` or `KIMI_HOST` — no third case exists to render.
+ */
+function renderForHost(host: HookInvocation['host'], text: string, stderr: string): HookResult {
+  if (host === KIMI_HOST) return ok(`${text}\n`, stderr)
+  return ok(JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }), stderr)
+}
+
+/**
+ * Load the global embedding model (see `vector.ts`'s header for why this is
+ * global, not repo-local like the enact-m5 reference). Additive: when it is
+ * absent or unreadable, the hook still advises from BM25 alone but must say
+ * so loudly — never silently.
+ *
+ * Gap fix over the reference (see `constants.ts`'s `modelDirMissingNote` /
+ * `modelArtifactCorruptNote` / `modelLoadErrorNote`): the reference's stderr
+ * note is one fixed generic string regardless of why the model failed to
+ * load. This classifies the failure into three distinguishable reasons,
+ * checked in this order:
+ *
+ *  1. the global artifact directory does not exist at all (nothing installed
+ *     yet) — checked directly with `existsSync` before touching anything
+ *     inside it;
+ *  2. the directory exists but the artifact inside it is missing files or
+ *     fails to parse/validate — `loadTokenizer` throwing (e.g. a missing or
+ *     malformed `tokenizer.json`) or `loadVectorHalf` returning `ok: false`
+ *     (its own `reason` already covers missing files, bad magic, a
+ *     manifest/header mismatch, or a byte-length mismatch);
+ *  3. anything else — `resolveGlobalArtifactDir` throwing (no HOME and no
+ *     XDG_CACHE_HOME) or any other unexpected exception.
+ *
+ * Every branch still returns `half: null`, so the hook always falls back to
+ * BM25-only search — this only makes the accompanying stderr note specific.
+ */
+function loadVector(env: HookInvocation['env']): { readonly half: VectorHalf | null; readonly note: string | null } {
+  let artifactDir: string
+  try {
+    artifactDir = resolveGlobalArtifactDir(env)
+  } catch (error) {
+    return { half: null, note: modelLoadErrorNote(error instanceof Error ? error.message : String(error)) }
+  }
+
+  if (!existsSync(artifactDir)) {
+    return { half: null, note: modelDirMissingNote(artifactDir) }
+  }
+
+  try {
+    const tokenizer = loadTokenizer(artifactDir)
+    const loaded = loadVectorHalf(artifactDir, tokenizer.tokenize)
+    if (loaded.ok) return { half: loaded.half, note: null }
+    // The directory exists; loadVectorHalf's own reason already distinguishes
+    // missing files / bad magic / a manifest mismatch / a truncated file.
+    return { half: null, note: modelArtifactCorruptNote(loaded.reason) }
+  } catch (error) {
+    // The directory exists but something in it (most likely tokenizer.json)
+    // is missing or fails to parse.
+    return { half: null, note: modelArtifactCorruptNote(error instanceof Error ? error.message : String(error)) }
+  }
+}
+
+/**
+ * The hook engine, parametrized by the already-resolved skill roots (see this
+ * module's header). `handler.ts` is the `HookHandler`-shaped adapter that
+ * resolves those roots from `adl-config.toml` and calls this.
+ */
+export async function runUserPromptSubmit(inv: HookInvocation, skillRoots: readonly string[]): Promise<HookResult> {
+  try {
+    // Hosts this hook has nothing to say to short-circuit before any work.
+    if (!JSON_CONTEXT_HOSTS.has(inv.host) && inv.host !== KIMI_HOST) return ok('')
+
+    // Opt-out escape hatch so a misbehaving matcher can never wedge the session.
+    if (inv.env[DISABLE_ENV] === '1') {
+      inv.record?.({ reason: `SKIP ${DISABLE_ENV}=1` })
+      return ok('')
+    }
+
+    // Every prompt is passed through stripOwnEcho first: a user quoting this
+    // hook's own suggestion back would otherwise score that skill's
+    // description against itself and get the same suggestion again, forever.
+    const prompt = stripOwnEcho(readPrompt(inv.payload))
+    if (prompt.trim().length < MIN_PROMPT_CHARS) {
+      inv.record?.({ reason: 'SKIP prompt too short' })
+      return ok('')
+    }
+
+    const skills = scanSkills(inv.root, skillRoots)
+    if (skills.length === 0) {
+      // WARN, not fail. Before adl-extensions retired the shared
+      // `.agents/skills/` pool there was exactly one place to look, so an empty
+      // corpus could only mean "install never ran" — worth exiting 1 over.
+      // Now the corpus is per-host AND per-extension, so empty has an innocent
+      // explanation it never had before: the repo is installed for a different
+      // host (`--host` narrowing is a supported install), or a declared
+      // extension ships no skills. Neither should kill the prompt.
+      //
+      // The loud signal for a genuine misinstall lives in `adl hook doctor`,
+      // which still FAILs on a missing corpus while hooks are enabled. That is
+      // the right place for it: doctor is the diagnostic, UserPromptSubmit is
+      // the hot path, and a dead prompt is a far worse failure than a missing
+      // suggestion.
+      const note = `adl: no SKILL.md files with name+description under ${skillRoots.join(', ')} — run \`adl hook doctor\` if that is unexpected`
+      inv.record?.({ reason: 'WARN no skills', message: note })
+      return ok('', `${note}\n`)
+    }
+
+    const config = buildMatchConfig(inv.env)
+
+    let vectorHalf: VectorHalf | null = null
+    let stderr = ''
+    if (config.vectorEnabled) {
+      const loaded = loadVector(inv.env)
+      vectorHalf = loaded.half
+      if (loaded.note) stderr = `${loaded.note}\n`
+    }
+
+    const matches = matchPrompt(prompt, skills, vectorHalf, config)
+    const suggested = matches.length === 0 ? '(none)' : matches.map((match) => match.name).join(', ')
+    inv.record?.({ reason: 'PASS', message: stderr.trim(), downstream: `skills: ${suggested}${vectorHalf ? ' (hybrid)' : ' (bm25)'}` })
+    if (matches.length === 0) return ok('', stderr)
+
+    return renderForHost(inv.host, renderMatches(matches), stderr)
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error)
+    // Exit 1, never 2: this hook advises, so a failure must surface loudly
+    // without blocking the prompt it was asked to annotate.
+    return fail(`adl: user-prompt-submit: ${message}`)
+  }
+}

package/packages/agent-hooks/src/hooks/user-prompt-submit/match.ts

@@ -0,0 +1,212 @@
+/**
+ * BM25 + hybrid vector skill ranking.
+ *
+ * Ported unchanged from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/match.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/src/match.mjs` in enact-m5). The tunable
+ * knobs (`MIN_SCORE`, `RELATIVE_FLOOR`, `COSINE_FLOOR`, `RRF_K`,
+ * `RRF_TEXT_WEIGHT`, `RRF_VECTOR_WEIGHT`, `TOP_K`) are threaded through as a
+ * `MatchConfig` rather than read from a module-level constants object — see
+ * `config.ts` and the header of `constants.ts` for why.
+ */
+import MiniSearch from 'minisearch'
+import type { MatchConfig } from './config.ts'
+import type { Skill } from './skills.ts'
+import { cosine, type VectorHalf } from './vector.ts'
+import { FIELD_BOOST, FUZZY, PREFIX, RANK1_BONUS, RANK3_BONUS, STOPWORDS } from './constants.ts'
+
+export interface SkillMatch {
+  readonly name: string
+  readonly description: string
+  readonly score: number
+}
+
+interface TextResult {
+  readonly label: string
+  readonly description: string
+  readonly score: number
+  readonly rank: number
+}
+
+interface VectorResult {
+  readonly skill: Skill
+  readonly cosine: number
+  readonly rank: number
+}
+
+interface FusedEntry {
+  readonly name: string
+  readonly description: string
+  readonly score: number
+}
+
+/** Lowercases and drops stopwords; applied to both indexed text and the query. */
+function processTerm(term: string): string | null {
+  const lowered = term.toLowerCase()
+  return lowered.length > 1 && !STOPWORDS.has(lowered) ? lowered : null
+}
+
+/**
+ * Builds the in-memory BM25 index. The corpus is a few dozen short documents,
+ * so it is rebuilt per invocation rather than persisted — that keeps the hook
+ * stateless and makes an edited SKILL.md take effect immediately.
+ */
+export function buildIndex(skills: readonly Skill[]): MiniSearch {
+  const index = new MiniSearch({
+    fields: ['name', 'keywords', 'description'],
+    storeFields: ['label', 'description'],
+    processTerm,
+    searchOptions: { boost: FIELD_BOOST, fuzzy: FUZZY, prefix: PREFIX, processTerm },
+  })
+  index.addAll(
+    skills.map((skill, id) => ({
+      id,
+      // Indexed split on separators so `resolving-merge-conflicts` matches
+      // "merge conflict"; `label` keeps the real name for display.
+      name: skill.name.replace(/[-_:]/g, ' '),
+      label: skill.name,
+      keywords: skill.keywords ?? '',
+      description: skill.description,
+    })),
+  )
+  return index
+}
+
+/**
+ * Ranks skills against the prompt. With a vector half, the two lists (BM25,
+ * cosine) are gated independently and fused with weighted Reciprocal Rank
+ * Fusion. Without one, the legacy BM25 path runs unchanged.
+ */
+export function matchPrompt(prompt: string, skills: readonly Skill[], vectorHalf: VectorHalf | null, config: MatchConfig): SkillMatch[] {
+  const textResults = gatedTextResults(prompt, skills, config)
+  const vectorResults = vectorHalf ? gatedVectorResults(prompt, skills, vectorHalf, config) : []
+
+  if (vectorResults.length === 0) {
+    return legacyRank(textResults, config).map((result) => ({
+      name: result.label,
+      description: result.description,
+      score: result.score,
+    }))
+  }
+
+  // Same quietness contract as the legacy path: a strong hit is not padded
+  // with weak cousins. Applied to the fused score, after sorting.
+  const fused = fuse(textResults, vectorResults, config).sort((a, b) => b.score - a.score)
+  const best = fused[0]?.score ?? 0
+  return fused.filter((entry) => entry.score >= best * config.relativeFloor).slice(0, config.topK)
+}
+
+/** BM25 candidates with the absolute floor applied, plus their 1-based ranks. */
+function gatedTextResults(prompt: string, skills: readonly Skill[], config: MatchConfig): TextResult[] {
+  const results = buildIndex(skills).search(prompt)
+  const best = (results[0]?.score as number | undefined) ?? 0
+  if (best < config.minScore) return []
+  return results
+    .filter((result) => (result.score as number) >= config.minScore)
+    .slice(0, config.vectorCandidates)
+    .map((result, index) => ({ label: result.label as string, description: result.description as string, score: result.score as number, rank: index + 1 }))
+}
+
+/** Cosine candidates over every skill, floor applied, 1-based ranks. */
+function gatedVectorResults(prompt: string, skills: readonly Skill[], vectorHalf: VectorHalf, config: MatchConfig): VectorResult[] {
+  const queryVec = vectorHalf.embed(prompt, { minTokens: config.vectorMinTokens })
+  if (!queryVec) return []
+
+  return skills
+    .map((skill) => ({ skill, vector: vectorHalf.embed(vectorDocText(skill)) }))
+    .filter((entry): entry is { skill: Skill; vector: Float32Array } => entry.vector !== null)
+    .map((entry) => ({ skill: entry.skill, cosine: cosine(queryVec, entry.vector) }))
+    .filter((entry) => entry.cosine >= config.cosineFloor)
+    .sort((a, b) => b.cosine - a.cosine)
+    .slice(0, config.vectorCandidates)
+    .map((entry, index) => ({ ...entry, rank: index + 1 }))
+}
+
+/** One embedding surface per skill: name, keywords, description. */
+function vectorDocText(skill: Skill): string {
+  return `${skill.name}. ${skill.keywords ? `${skill.keywords}. ` : ''}${skill.description}`
+}
+
+/**
+ * Weighted RRF, mirroring enact-docs-search's hybridSearch: each list
+ * contributes weight/(RRF_K + rank), plus a small positional bonus for being
+ * ranked #1 (or <=3) in either list. Skills in both lists get both terms.
+ */
+function fuse(textResults: readonly TextResult[], vectorResults: readonly VectorResult[], config: MatchConfig): FusedEntry[] {
+  const byName = new Map<string, { name: string; description: string; textRank?: number; vectorRank?: number }>()
+
+  for (const result of textResults) {
+    byName.set(result.label, { name: result.label, description: result.description, textRank: result.rank })
+  }
+  for (const result of vectorResults) {
+    const existing = byName.get(result.skill.name)
+    if (existing) {
+      byName.set(result.skill.name, { ...existing, vectorRank: result.rank })
+    } else {
+      byName.set(result.skill.name, { name: result.skill.name, description: result.skill.description, vectorRank: result.rank })
+    }
+  }
+
+  return [...byName.values()].map((entry) => scoreFusedEntry(entry, config)).sort((a, b) => b.score - a.score)
+}
+
+function rankContribution(rank: number | undefined, weight: number, rrfK: number): number {
+  if (!rank) return 0
+  const bonus = rank === 1 ? RANK1_BONUS : rank <= 3 ? RANK3_BONUS : 0
+  return weight / (rrfK + rank) + bonus
+}
+
+function scoreFusedEntry(entry: { name: string; description: string; textRank?: number; vectorRank?: number }, config: MatchConfig): FusedEntry {
+  const score = rankContribution(entry.textRank, config.rrfTextWeight, config.rrfK) + rankContribution(entry.vectorRank, config.rrfVectorWeight, config.rrfK)
+  return { name: entry.name, description: entry.description, score }
+}
+
+/** The pre-hybrid ranking: absolute floor plus the relative floor, no fusion. */
+function legacyRank(results: readonly TextResult[], config: MatchConfig): TextResult[] {
+  if (results.length === 0) return []
+  const best = results[0]?.score ?? 0
+  return results.filter((result) => result.score >= best * config.relativeFloor).slice(0, config.topK)
+}
+
+/** Renders matches as the context block injected into the session. */
+// One line of preamble, not a paragraph: every token here is burned on every
+// prompt that matches. The stable prefix 'Skills matching this prompt' is
+// what stripOwnEcho keys on — it must survive wording changes so old pasted
+// blocks still strip.
+export const BANNER_FIRST_LINE = 'Advisory: Skills matching this prompt, only invoke if its related to the task:'
+
+export function renderMatches(matches: readonly SkillMatch[]): string {
+  const lines = matches.map((match) => `  ${match.name} — ${truncate(match.description, 140)}`)
+  return [BANNER_FIRST_LINE, ...lines].join('\n')
+}
+
+// Strip any of THIS hook's own previous output that the user pasted back into
+// their prompt. Without this the matcher scores its own banner and the skill
+// descriptions inside it, re-suggesting the same skills forever. Cut from the
+// banner to the end of the indented skill list it introduces, keeping
+// everything else, so the user's actual words in the same message are still
+// matched normally.
+export function stripOwnEcho(prompt: string): string {
+  const lines = String(prompt).split('\n')
+  const out: string[] = []
+  let skipping = false
+  for (const line of lines) {
+    if (line.includes('Skills matching this prompt')) {
+      skipping = true
+      continue
+    }
+    if (skipping) {
+      // The block is the banner's second line plus the two-space-indented
+      // "  name — description" entries. Anything else ends it.
+      if (line.trim() === '' || /^\s{2,}\S/.test(line) || line.includes('not a directive')) continue
+      skipping = false
+    }
+    out.push(line)
+  }
+  return out.join('\n')
+}
+
+function truncate(text: string, limit: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`
+}

package/packages/agent-hooks/src/hooks/user-prompt-submit/skill-roots.ts

@@ -0,0 +1,73 @@
+/**
+ * Where a repo's skill corpus lives, per host.
+ *
+ * adl-extensions HARDCUT to one plugin root per host, each namespaced by
+ * extension, and retired the flat shared `.agents/skills/` pool. That pool was
+ * this package's ONE host-independent default, and an empty corpus is
+ * `fail()` on UserPromptSubmit — so resolving the new layout is not a nicety,
+ * it is what keeps every prompt in every managed repo from exiting 1.
+ *
+ * ROSTER-DRIVEN, deliberately, not a glob over `<plugin-root>/*`: "installed"
+ * means "declared in `[extensions]`". Uninstall removes the
+ * `[extensions.<name>]` table and the plugin root together, so a plugin root
+ * left behind by a failed uninstall is drift — and drift must not silently
+ * re-arm a skill that nothing declares.
+ *
+ * Layout, from adl-extensions' own `MANIFEST_BY_PLATFORM`:
+ *
+ *   claude    .claude-plugin/<name>/skills/<skill>/SKILL.md
+ *   codex     .codex-plugin/<name>/skills/<skill>/SKILL.md
+ *   cursor    .cursor-plugin/<name>/skills/<skill>/SKILL.md
+ *   kimi      .kimi-plugin/<name>/skills/<skill>/SKILL.md
+ *   opencode  .opencode/skills/<skill>/SKILL.md      flat, NOT per-extension
+ *
+ * OpenCode differs in SHAPE, not just location: its plugin surface has no
+ * skills concept, so its skills are not namespaced per extension and the
+ * roster says nothing useful about them.
+ *
+ * Every returned root is a path that MAY exist. `scanSkills` skips missing
+ * ones, which is exactly right here: a declared extension legitimately has no
+ * root for the current host (`--host` narrowing is a supported install), and a
+ * bundle may ship no skills at all. Neither is an error.
+ */
+
+import type { HostId } from '../contract.ts'
+
+/** The pre-HARDCUT shared pool, still scanned last so un-reinstalled repos keep working. */
+export const LEGACY_SKILLS_DIR = '.agents/skills'
+
+/** Per-host plugin directory. OpenCode is absent: it is flat, handled below. */
+const PLUGIN_DIR: Partial<Record<HostId, string>> = {
+  claude: '.claude-plugin',
+  codex: '.codex-plugin',
+  cursor: '.cursor-plugin',
+  kimi: '.kimi-plugin',
+}
+
+/** OpenCode's flat, un-namespaced skills directory. */
+const OPENCODE_SKILLS_DIR = '.opencode/skills'
+
+/**
+ * A roster key is a TOML sub-table name, but it reaches us from a file on
+ * disk, so it is never pasted into a path unchecked: anything carrying a
+ * separator, a traversal, or nothing at all is dropped rather than resolved.
+ */
+function isUsableName(name: string): boolean {
+  return name.length > 0 && !name.includes('/') && !name.includes('\\') && name !== '.' && name !== '..'
+}
+
+/**
+ * Skill roots to scan for `host`, given the extensions declared in
+ * `adl-config.toml`'s `[extensions]` table, in roster order. The legacy pool
+ * is always last, so a declared extension wins a name collision against a
+ * stale copy left in it.
+ */
+export function skillRootsFor(host: HostId, roster: readonly string[]): readonly string[] {
+  if (host === 'opencode') return [OPENCODE_SKILLS_DIR, LEGACY_SKILLS_DIR]
+
+  const pluginDir = PLUGIN_DIR[host]
+  if (pluginDir === undefined) return [LEGACY_SKILLS_DIR]
+
+  const roots = roster.filter(isUsableName).map((name) => `${pluginDir}/${name}/skills`)
+  return [...roots, LEGACY_SKILLS_DIR]
+}

package/packages/agent-hooks/src/hooks/user-prompt-submit/skills.ts

@@ -0,0 +1,98 @@
+/**
+ * SKILL.md discovery and frontmatter parsing.
+ *
+ * Ported unchanged from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/skills.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/utils/skills.mjs` in enact-m5).
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface Skill {
+  readonly name: string
+  readonly description: string
+  readonly keywords: string
+  readonly source: string
+  readonly dir: string
+}
+
+function stripQuotes(value: string): string {
+  const trimmed = value.trim()
+  if (trimmed.length >= 2 && (trimmed.startsWith('"') || trimmed.startsWith("'"))) {
+    const quote = trimmed[0]
+    if (trimmed.endsWith(quote as string)) return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+/**
+ * Minimal frontmatter reader for the `key: value` pairs SKILL.md files use.
+ * Values continuing on indented lines are folded onto one line.
+ * Returns null when the file has no leading `---` block.
+ */
+export function parseFrontmatter(text: string): Record<string, string> | null {
+  const lines = text.split('\n')
+  if (lines[0]?.trim() !== '---') return null
+  const end = lines.indexOf('---', 1)
+  if (end === -1) return null
+
+  const fields: Record<string, string> = {}
+  let currentKey: string | null = null
+  for (const line of lines.slice(1, end)) {
+    const match = /^([A-Za-z_][\w-]*):[ \t]*(.*)$/.exec(line)
+    if (match) {
+      currentKey = match[1] as string
+      fields[currentKey] = (match[2] as string).trim()
+      continue
+    }
+    if (currentKey !== null && /^[ \t]+\S/.test(line)) {
+      fields[currentKey] = `${fields[currentKey]} ${line.trim()}`.trim()
+    }
+  }
+
+  for (const key of Object.keys(fields)) fields[key] = stripQuotes(fields[key] as string)
+  return fields
+}
+
+interface ReadSkillResult {
+  readonly realPath: string
+  readonly value: { readonly name: string; readonly description: string; readonly keywords: string }
+}
+
+function readSkill(rootPath: string, entryName: string, isDirLike: boolean): ReadSkillResult | null {
+  if (!isDirLike) return null
+  const skillFile = join(rootPath, entryName, 'SKILL.md')
+  if (!existsSync(skillFile)) return null
+  const realPath = realpathSync(skillFile)
+
+  const fields = parseFrontmatter(readFileSync(skillFile, 'utf8'))
+  const name = fields?.name?.trim()
+  const description = fields?.description?.trim()
+  if (!name || !description) return null
+  const keywords = [fields?.keywords, fields?.['when-to-use']].filter(Boolean).join(' ')
+  return { realPath, value: { name, description, keywords } }
+}
+
+/**
+ * Scans the configured skill roots for SKILL.md files carrying both a name and
+ * a description. Directories reached through more than one root are
+ * de-duplicated by real path.
+ */
+export function scanSkills(repoRoot: string, roots: readonly string[]): Skill[] {
+  const found = new Map<string, Skill>()
+
+  for (const root of roots) {
+    const rootPath = join(repoRoot, root)
+    if (!existsSync(rootPath)) continue
+
+    for (const entry of readdirSync(rootPath, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+      const skill = readSkill(rootPath, entry.name, true)
+      if (skill && !found.has(skill.realPath)) {
+        found.set(skill.realPath, { ...skill.value, source: root, dir: entry.name })
+      }
+    }
+  }
+
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name))
+}