lyra-core 0.1.0

package/src/sandbox/types.ts

@@ -0,0 +1,129 @@
+/**
+ * Sandbox abstraction for limb execution.
+ *
+ * Phase 9.5 (Apr 28 2026 incident response). Lyra's limbs run on the operator's
+ * host. Permission floors (PathGuard + dangerous-pattern modal + strict/prompt/yolo)
+ * caught the rm correctly during the v0.9.3 benchmark, but once the modal granted
+ * `s` (allow session), the command ran on the real host with full FS access. The
+ * cascade (tmux socket → daemon detach → orphan name-slot blocking) was severe.
+ *
+ * This module adds a structural layer BENEATH the permission floor: every
+ * spawn() call from a tool is routed through a `SandboxBackend` which can wrap
+ * the command in an OS sandbox before execution. Even if the permission floor
+ * is bypassed (yolo, allow-session, allow-once), the sandbox profile prevents
+ * writes outside an allowlist.
+ *
+ * Mirrors hermes-agent's TERMINAL_ENV pattern (local | docker | modal | daytona |
+ * singularity | ssh) but starts smaller: `none` (passthrough) and `os` (macOS
+ * sandbox-exec / future Linux bubblewrap). Docker mode is a separate followup
+ * bundle.
+ */
+
+import type { SpawnOptions } from 'node:child_process'
+
+/**
+ * Mode selector. Lives under `sandbox.mode` in `~/.lyra/config.ts`.
+ *
+ *  - `none`: passthrough (today's behaviour). No sandboxing applied. Default
+ *    for backward compatibility while Tier 2 stabilizes.
+ *  - `os`: native OS sandbox. macOS uses sandbox-exec with a deny-default
+ *    seatbelt profile. Linux uses bubblewrap (post-MVP). On unsupported
+ *    platforms falls back to `none` with a startup warning.
+ *  - `docker`: long-lived container per session, every spawn goes through
+ *    `docker exec`. Future bundle.
+ */
+export type SandboxMode = 'none' | 'os' | 'docker'
+
+/**
+ * Inputs the factory needs to construct a backend.
+ *  - `agentDir`: write-allowed (lyra writes activity log, mcp debug, etc.).
+ *  - `workspaceRoot`: write-allowed (where the operator launched lyra from;
+ *    fs.write/fs.patch authorized through the modal land here).
+ *  - `homedir`: used by the seatbelt profile to deny secret-bearing subdirs
+ *    (`~/.ssh`, `~/.aws`, `~/Library/Keychains`, `~/.config/gcloud`).
+ *  - `extraWriteAllow`: optional extra subpaths to allow writes under (test
+ *    sandbox dirs, custom workspaces).
+ *  - `extraWriteDeny`: optional extra subpaths to explicitly block writes.
+ */
+export interface SandboxBackendOpts {
+  agentDir: string
+  workspaceRoot: string
+  homedir: string
+  extraWriteAllow?: string[]
+  extraWriteDeny?: string[]
+}
+
+/**
+ * One spawn request, fully described before the backend wraps it. We pass
+ * `argv` rather than the legacy `(command, options)` form because backends
+ * that prepend `sandbox-exec -p ...` need to construct an explicit argv;
+ * mixing `shell: true` with a wrapper produces confused quoting.
+ */
+export interface WrappedSpawn {
+  /** The binary that should actually be exec'd. May be the original, may be a wrapper. */
+  command: string
+  /** Args to pass. Wrapper backends prepend their own. */
+  args: string[]
+  /** SpawnOptions to pass through. `shell` is intentionally omitted because the wrapper builds the explicit argv. */
+  options: SpawnOptions
+}
+
+/**
+ * Inputs the tool layer hands the backend per spawn. The backend wraps the
+ * argv (e.g. prepend `sandbox-exec -p <profile>` or rewrite as `docker exec
+ * <containerId> ...`). For shell.run-style tools, the caller MUST pass an
+ * explicit argv (`command='/bin/sh', args=['-c', userCommand]`) — the backend
+ * cannot use `shell: true` because the wrapper builds the argv itself.
+ */
+export interface SandboxSpawnRequest {
+  command: string
+  args: string[]
+  options: SpawnOptions
+}
+
+/**
+ * Environment hint surfaced to the brain via the frozen prefix's # Environment
+ * block. Lets the brain skip the "run pwd + ls / + uname to figure out where
+ * I am" empirical-discovery dance — saves wasted tool calls when the brain
+ * defaults to host-style commands inside a Linux container (BSD sed, fs.read
+ * /workspace ENOENT, etc.).
+ *
+ * Each non-passthrough backend implements `envHint()` to surface its specific
+ * shape. `LocalBackend` returns null (no sandbox, no hint).
+ */
+export interface SandboxEnvHint {
+  mode: SandboxMode
+  label: string
+  innerOs?: 'linux' | 'darwin' | null
+  workspaceMount?: string | null
+  scope?: string | null
+}
+
+/**
+ * The backend interface. Implementations: LocalBackend (passthrough),
+ * MacOSSandboxExecBackend (sandbox-exec wrapper), LinuxBubblewrapBackend
+ * (bwrap wrapper), DockerBackend (per-session container).
+ *
+ * `wrapSpawn` is async to allow lifecycle work (e.g. DockerBackend lazy-starts
+ * the container on first call). Sync backends just `return Promise.resolve(...)`.
+ * Optional `dispose` lets backends clean up (DockerBackend kills its container).
+ * Optional `envHint` returns a brain-facing description of the sandbox shape.
+ */
+export interface SandboxBackend {
+  /** Backend identifier surfaced in logs / debug output. */
+  readonly mode: SandboxMode
+  /** Backend label including platform detail (e.g. 'os:darwin', 'docker:oven/bun:1'). */
+  readonly label: string
+  /**
+   * Wrap a spawn request. Returns (a Promise of) the argv that should be
+   * passed to `spawn(command, args, options)`. For `none`, returns the request
+   * unchanged. For `os`, returns a sandbox-exec wrapper. For `docker`, returns
+   * `docker exec <containerId> <orig-command>`, awaiting container start on
+   * the first call.
+   */
+  wrapSpawn(req: SandboxSpawnRequest): Promise<WrappedSpawn>
+  /** Optional cleanup (kill long-lived containers, remove temp files). Called on lyra exit. */
+  dispose?(): Promise<void>
+  /** Optional brain-facing description of the sandbox shape. Null for passthrough. */
+  envHint?(): SandboxEnvHint | null
+}

package/src/skills/index.ts

@@ -0,0 +1,8 @@
+export type { SkillFrontmatter, SkillRef, SkillSource } from './types'
+export { scanSkills, parseFrontmatter, type SkillScannerOptions } from './scanner'
+export {
+  matchTriggers,
+  matchFilePattern,
+  matchBashPattern,
+  type SkillTriggerMatch,
+} from './triggers'

package/src/skills/scanner.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parseFrontmatter, scanSkills } from './scanner'
+
+let scratch: string
+
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), 'lyra-skills-scanner-'))
+})
+
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true })
+})
+
+async function plant(absDir: string, fm: string, body = '# body\n'): Promise<void> {
+  await mkdir(absDir, { recursive: true })
+  await writeFile(join(absDir, 'SKILL.md'), `${fm}\n\n${body}`)
+}
+
+describe('parseFrontmatter', () => {
+  it('parses top-level fields', () => {
+    const fm = parseFrontmatter('---\nname: foo\ndescription: hi\nversion: 1.0.0\n---\n\nbody')
+    expect(fm.name).toBe('foo')
+    expect(fm.description).toBe('hi')
+    expect(fm.version).toBe('1.0.0')
+  })
+
+  it('parses metadata.filePattern + metadata.bashPattern', () => {
+    const raw =
+      '---\nname: dogfood\ndescription: tests\nmetadata:\n  filePattern: "*.test.ts,*.spec.ts"\n  bashPattern: "playwright|jest"\n---\n\nbody'
+    const fm = parseFrontmatter(raw)
+    expect(fm.filePattern).toBe('*.test.ts,*.spec.ts')
+    expect(fm.bashPattern).toBe('playwright|jest')
+  })
+
+  it('parses argument-hint as argumentHint', () => {
+    const fm = parseFrontmatter('---\nname: c\nargument-hint: <message>\n---\n\nbody')
+    expect(fm.argumentHint).toBe('<message>')
+  })
+
+  it('returns empty object for non-frontmatter content', () => {
+    expect(parseFrontmatter('# just a heading\nblah')).toEqual({})
+  })
+})
+
+describe('scanSkills', () => {
+  it('finds lyra + claude-code skills + claude plugin cache layouts', async () => {
+    const lyraSkillsRoot = join(scratch, '.lyra', 'skills')
+    const claudeSkillsRoot = join(scratch, '.claude', 'skills')
+    const claudePluginsCacheRoot = join(scratch, '.claude', 'plugins', 'cache')
+
+    await plant(join(lyraSkillsRoot, 'dogfood'), '---\nname: dogfood\ndescription: lyra skill\n---')
+    await plant(
+      join(claudeSkillsRoot, 'commit'),
+      '---\nname: commit\ndescription: claude skill\n---',
+    )
+    await plant(
+      join(claudePluginsCacheRoot, 'awesome', 'pdf', '1.0.0', 'skills', 'extract'),
+      '---\nname: extract\ndescription: pdf skill\n---',
+    )
+    // Plugin with direct SKILL.md (no skills/ subdir)
+    await plant(
+      join(claudePluginsCacheRoot, 'awesome', 'docx', '1.0.0'),
+      '---\nname: docx\ndescription: docx skill\n---',
+    )
+
+    const skills = await scanSkills({
+      lyraSkillsRoot,
+      lyraPluginsRoot: join(scratch, '.lyra', 'plugins'),
+      claudeSkillsRoot,
+      claudePluginsCacheRoot,
+      importsClaudeCode: true,
+    })
+    const ids = skills.map(s => s.id).sort()
+    expect(ids).toContain('lyra:dogfood')
+    expect(ids).toContain('claude-code:commit')
+    expect(ids).toContain('claude-plugin:awesome:pdf:extract')
+    expect(ids).toContain('claude-plugin:awesome:docx')
+    const pdf = skills.find(s => s.id === 'claude-plugin:awesome:pdf:extract')
+    expect(pdf?.pluginCoord?.marketplace).toBe('awesome')
+    expect(pdf?.pluginCoord?.plugin).toBe('pdf')
+    expect(pdf?.pluginCoord?.version).toBe('1.0.0')
+  })
+
+  it('skips claude paths when imports.claudeCode is false', async () => {
+    const claudeSkillsRoot = join(scratch, '.claude', 'skills')
+    await plant(join(claudeSkillsRoot, 'foo'), '---\nname: foo\ndescription: x\n---')
+    const skills = await scanSkills({
+      lyraSkillsRoot: join(scratch, 'doesnotexist'),
+      lyraPluginsRoot: join(scratch, 'doesnotexist'),
+      claudeSkillsRoot,
+      claudePluginsCacheRoot: join(scratch, 'doesnotexist'),
+      importsClaudeCode: false,
+    })
+    expect(skills).toEqual([])
+  })
+
+  it('discovers lyra-plugin skills', async () => {
+    const lyraPluginsRoot = join(scratch, '.lyra', 'plugins')
+    await plant(
+      join(lyraPluginsRoot, 'system', 'skills', 'sweep'),
+      '---\nname: sweep\ndescription: plugin-sourced skill\n---',
+    )
+    const skills = await scanSkills({
+      lyraSkillsRoot: join(scratch, 'doesnotexist'),
+      lyraPluginsRoot,
+      claudeSkillsRoot: join(scratch, 'doesnotexist'),
+      claudePluginsCacheRoot: join(scratch, 'doesnotexist'),
+      importsClaudeCode: false,
+    })
+    expect(skills.map(s => s.id)).toEqual(['lyra-plugin:system:sweep'])
+  })
+})
+
+describe('skills without YAML frontmatter', () => {
+  it('still surfaces skills whose SKILL.md has no frontmatter (fallback to dir name + first body line)', async () => {
+    const lyraSkillsRoot = join(scratch, '.lyra', 'skills')
+    await mkdir(join(lyraSkillsRoot, 'no-fm'), { recursive: true })
+    await writeFile(
+      join(lyraSkillsRoot, 'no-fm', 'SKILL.md'),
+      '# no-fm skill\n\nA skill without yaml frontmatter that should still be discoverable.\n',
+    )
+    const skills = await scanSkills({
+      lyraSkillsRoot,
+      lyraPluginsRoot: join(scratch, 'doesnotexist'),
+      claudeSkillsRoot: join(scratch, 'doesnotexist'),
+      claudePluginsCacheRoot: join(scratch, 'doesnotexist'),
+      importsClaudeCode: false,
+    })
+    const found = skills.find(s => s.id === 'lyra:no-fm')
+    expect(found).toBeDefined()
+    expect(found!.name).toBe('no-fm')
+    expect(found!.description).toContain('A skill without yaml frontmatter')
+  })
+})

package/src/skills/scanner.ts

@@ -0,0 +1,257 @@
+import type { Dirent } from 'node:fs'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { agentPaths } from '../paths'
+import type { SkillFrontmatter, SkillRef, SkillSource } from './types'
+
+/**
+ * Scan the canonical skill locations and return parsed SkillRefs. Skips paths
+ * that don't exist or aren't directories so callers can register all sources
+ * eagerly without needing to probe individually.
+ */
+export interface SkillScannerOptions {
+  /** Whether to scan ~/.claude/skills/ + ~/.claude/plugins/cache/. Default true. */
+  importsClaudeCode?: boolean
+  /** Override for ~/.lyra/skills/ (test seam). Defaults to agentPaths.skills. */
+  lyraSkillsRoot?: string
+  /** Override for ~/.lyra/plugins/ (test seam). Defaults to agentPaths.plugins. */
+  lyraPluginsRoot?: string
+  /** Override for ~/.claude/skills/ (test seam). Defaults to ~/.claude/skills. */
+  claudeSkillsRoot?: string
+  /** Override for ~/.claude/plugins/cache/ (test seam). Defaults to ~/.claude/plugins/cache. */
+  claudePluginsCacheRoot?: string
+}
+
+export async function scanSkills(opts: SkillScannerOptions = {}): Promise<SkillRef[]> {
+  const importsClaudeCode = opts.importsClaudeCode ?? true
+  const lyraSkillsRoot = opts.lyraSkillsRoot ?? agentPaths.skills
+  const lyraPluginsRoot = opts.lyraPluginsRoot ?? agentPaths.plugins
+  const claudeSkillsRoot = opts.claudeSkillsRoot ?? join(homedir(), '.claude', 'skills')
+  const claudePluginsCacheRoot =
+    opts.claudePluginsCacheRoot ?? join(homedir(), '.claude', 'plugins', 'cache')
+
+  const refs: SkillRef[] = []
+  await collectSimple(lyraSkillsRoot, 'lyra', refs)
+  await collectLyraPluginSkills(lyraPluginsRoot, refs)
+  if (importsClaudeCode) {
+    await collectSimple(claudeSkillsRoot, 'claude-code', refs)
+    await collectClaudePluginCacheSkills(claudePluginsCacheRoot, refs)
+  }
+  return refs
+}
+
+async function dirEntries(path: string): Promise<Dirent[] | null> {
+  try {
+    const s = await stat(path)
+    if (!s.isDirectory()) return null
+  } catch {
+    return null
+  }
+  try {
+    return (await readdir(path, { withFileTypes: true })) as Dirent[]
+  } catch {
+    return null
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    const s = await stat(path)
+    return s.isFile()
+  } catch {
+    return false
+  }
+}
+
+async function collectSimple(
+  root: string,
+  source: Extract<SkillSource, 'lyra' | 'claude-code'>,
+  out: SkillRef[],
+): Promise<void> {
+  const entries = await dirEntries(root)
+  if (!entries) return
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const skillPath = join(root, entry.name, 'SKILL.md')
+    if (!(await fileExists(skillPath))) continue
+    const ref = await loadSkill(skillPath, entry.name, source)
+    if (ref) out.push(ref)
+  }
+}
+
+async function collectLyraPluginSkills(pluginsRoot: string, out: SkillRef[]): Promise<void> {
+  const plugins = await dirEntries(pluginsRoot)
+  if (!plugins) return
+  for (const plugin of plugins) {
+    if (!plugin.isDirectory()) continue
+    const skillsRoot = join(pluginsRoot, plugin.name, 'skills')
+    const skills = await dirEntries(skillsRoot)
+    if (!skills) continue
+    for (const skill of skills) {
+      if (!skill.isDirectory()) continue
+      const skillPath = join(skillsRoot, skill.name, 'SKILL.md')
+      if (!(await fileExists(skillPath))) continue
+      const ref = await loadSkill(skillPath, `${plugin.name}:${skill.name}`, 'lyra-plugin')
+      if (ref) out.push(ref)
+    }
+  }
+}
+
+async function collectClaudePluginCacheSkills(cacheRoot: string, out: SkillRef[]): Promise<void> {
+  const marketplaces = await dirEntries(cacheRoot)
+  if (!marketplaces) return
+  for (const marketplace of marketplaces) {
+    if (!marketplace.isDirectory()) continue
+    const marketDir = join(cacheRoot, marketplace.name)
+    const plugins = await dirEntries(marketDir)
+    if (!plugins) continue
+    for (const plugin of plugins) {
+      if (!plugin.isDirectory()) continue
+      // Layer 1: <market>/<plugin>/<version>/skills/<skill>/SKILL.md
+      // Layer 2: <market>/<plugin>/skills/<skill>/SKILL.md (no version dir)
+      // Try the version layer first; fall back to direct.
+      const versions = await dirEntries(join(marketDir, plugin.name))
+      if (!versions) continue
+      for (const versionEntry of versions) {
+        if (!versionEntry.isDirectory()) continue
+        const versionDir = join(marketDir, plugin.name, versionEntry.name)
+        // Two valid shapes; both checked.
+        await collectClaudeSkillsFromVersion(
+          versionDir,
+          marketplace.name,
+          plugin.name,
+          versionEntry.name,
+          out,
+        )
+      }
+    }
+  }
+}
+
+async function collectClaudeSkillsFromVersion(
+  versionDir: string,
+  marketplace: string,
+  plugin: string,
+  version: string,
+  out: SkillRef[],
+): Promise<void> {
+  const skillsDir = join(versionDir, 'skills')
+  const direct = await fileExists(join(versionDir, 'SKILL.md'))
+  if (direct) {
+    const ref = await loadSkill(
+      join(versionDir, 'SKILL.md'),
+      `${marketplace}:${plugin}`,
+      'claude-plugin',
+    )
+    if (ref) {
+      ref.pluginCoord = { marketplace, plugin, version }
+      out.push(ref)
+    }
+  }
+  const skills = await dirEntries(skillsDir)
+  if (!skills) return
+  for (const skill of skills) {
+    if (!skill.isDirectory()) continue
+    const skillPath = join(skillsDir, skill.name, 'SKILL.md')
+    if (!(await fileExists(skillPath))) continue
+    const id = `${marketplace}:${plugin}:${skill.name}`
+    const ref = await loadSkill(skillPath, id, 'claude-plugin')
+    if (ref) {
+      ref.pluginCoord = { marketplace, plugin, version }
+      out.push(ref)
+    }
+  }
+}
+
+async function loadSkill(
+  path: string,
+  fallbackId: string,
+  source: SkillSource,
+): Promise<SkillRef | null> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return null
+  }
+  const fm = parseFrontmatter(raw)
+  // Skills without YAML frontmatter are still surfaced; we derive name from
+  // the directory and description from the first heading or paragraph so the
+  // brain can find them via `skills.list`.
+  const name = fm.name ?? fallbackId
+  const description = fm.description ?? deriveDescription(raw)
+  return {
+    id: `${source}:${fallbackId}`,
+    name,
+    description,
+    path,
+    source,
+    frontmatter: { name, description, ...fm },
+  }
+}
+
+function deriveDescription(raw: string): string {
+  const body = raw.startsWith('---') ? raw.slice(raw.indexOf('\n---', 4) + 4) : raw
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    if (trimmed.startsWith('#')) continue
+    return trimmed.slice(0, 200)
+  }
+  return ''
+}
+
+const KEY_RE = /^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/
+
+/**
+ * Minimal YAML frontmatter parser (top-level + one nested level for `metadata:`).
+ * We avoid pulling in a full YAML lib because skills only need a tiny subset and
+ * scan time runs on every chat boot.
+ */
+export function parseFrontmatter(raw: string): Partial<SkillFrontmatter> {
+  if (!raw.startsWith('---')) return {}
+  const end = raw.indexOf('\n---', 4)
+  if (end === -1) return {}
+  const block = raw.slice(4, end)
+  const out: Partial<SkillFrontmatter> = {}
+  let inMetadata = false
+  for (const rawLine of block.split('\n')) {
+    if (rawLine.trim() === '') {
+      inMetadata = false
+      continue
+    }
+    const indented = rawLine.startsWith('  ') || rawLine.startsWith('\t')
+    const trimmed = rawLine.trim()
+    if (!indented) {
+      inMetadata = false
+      const m = trimmed.match(KEY_RE)
+      if (!m?.[1]) continue
+      const key = m[1]
+      const value = unquote(m[2] ?? '')
+      if (key === 'name') out.name = value
+      else if (key === 'description') out.description = value
+      else if (key === 'version') out.version = value
+      else if (key === 'license') out.license = value
+      else if (key === 'argument-hint' || key === 'argumentHint') out.argumentHint = value
+      else if (key === 'metadata') inMetadata = true
+      continue
+    }
+    if (!inMetadata) continue
+    const m = trimmed.match(KEY_RE)
+    if (!m?.[1]) continue
+    const key = m[1]
+    const value = unquote(m[2] ?? '')
+    if (key === 'filePattern') out.filePattern = value
+    else if (key === 'bashPattern') out.bashPattern = value
+  }
+  return out
+}
+
+function unquote(s: string): string {
+  const t = s.trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1)
+  }
+  return t
+}

package/src/skills/triggers.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'bun:test'
+import { matchBashPattern, matchFilePattern, matchTriggers } from './triggers'
+import type { SkillRef } from './types'
+
+describe('matchFilePattern', () => {
+  it('matches single glob against basename', () => {
+    expect(matchFilePattern('*.test.ts', '/tmp/foo.test.ts')).toBe(true)
+    expect(matchFilePattern('*.test.ts', '/tmp/foo.ts')).toBe(false)
+  })
+  it('matches comma-separated globs', () => {
+    expect(matchFilePattern('*.test.ts,*.spec.ts', '/tmp/foo.spec.ts')).toBe(true)
+    expect(matchFilePattern('*.test.ts,*.spec.ts', '/tmp/foo.md')).toBe(false)
+  })
+})
+
+describe('matchBashPattern', () => {
+  it('matches regex anywhere in command', () => {
+    expect(matchBashPattern('playwright|jest', 'bun run jest tests/')).toBe(true)
+    expect(matchBashPattern('playwright|jest', 'go test ./...')).toBe(false)
+  })
+  it('returns false on invalid regex', () => {
+    expect(matchBashPattern('[invalid', 'foo')).toBe(false)
+  })
+})
+
+function ref(filePattern?: string, bashPattern?: string): SkillRef {
+  return {
+    id: 'lyra:t',
+    name: 't',
+    description: '',
+    path: '/tmp/SKILL.md',
+    source: 'lyra',
+    frontmatter: {
+      name: 't',
+      description: '',
+      ...(filePattern ? { filePattern } : {}),
+      ...(bashPattern ? { bashPattern } : {}),
+    },
+  }
+}
+
+describe('matchTriggers', () => {
+  it('matches fs.write paths against filePattern', () => {
+    const skills = [ref('*.test.ts')]
+    const out = matchTriggers(
+      { name: 'fs.write', args: { path: '/tmp/foo.test.ts', text: 'x' } },
+      skills,
+    )
+    expect(out).toHaveLength(1)
+    expect(out[0]!.reason).toBe('filePattern')
+  })
+
+  it('matches shell.run commands against bashPattern', () => {
+    const skills = [ref(undefined, 'jest')]
+    const out = matchTriggers(
+      { name: 'shell.run', args: { command: 'bun run jest tests/' } },
+      skills,
+    )
+    expect(out).toHaveLength(1)
+    expect(out[0]!.reason).toBe('bashPattern')
+  })
+
+  it('returns empty when nothing matches', () => {
+    const skills = [ref('*.spec.ts'), ref(undefined, 'rspec')]
+    const out = matchTriggers(
+      { name: 'fs.write', args: { path: '/tmp/foo.md', text: 'x' } },
+      skills,
+    )
+    expect(out).toEqual([])
+  })
+
+  it('ignores non-matching tool names', () => {
+    const skills = [ref('*.md')]
+    const out = matchTriggers({ name: 'memory.save', args: { path: '/tmp/foo.md' } }, skills)
+    expect(out).toEqual([])
+  })
+})

package/src/skills/triggers.ts

@@ -0,0 +1,78 @@
+import type { SkillRef } from './types'
+
+/**
+ * Match a comma-separated glob list (`*.test.ts,*.spec.ts`) against an
+ * absolute path. Globs are matched against the basename and against the
+ * trailing path segment (e.g. `tests/foo.spec.ts` matches `tests/*.spec.ts`).
+ */
+export function matchFilePattern(pattern: string, absPath: string): boolean {
+  const globs = pattern
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (globs.length === 0) return false
+  const basename = absPath.split('/').pop() ?? absPath
+  for (const g of globs) {
+    if (globToRegex(g).test(basename) || globToRegex(g).test(absPath)) return true
+  }
+  return false
+}
+
+export function matchBashPattern(pattern: string, command: string): boolean {
+  try {
+    return new RegExp(pattern).test(command)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Find skills whose triggers match the given tool call. Returns the matched
+ * skills paired with the reason (so the brain sees "auto-loaded by file
+ * pattern" or "auto-loaded by bash pattern" in the injected context).
+ */
+export interface SkillTriggerMatch {
+  skill: SkillRef
+  reason: 'filePattern' | 'bashPattern'
+}
+
+export function matchTriggers(
+  call: { name: string; args: unknown },
+  skills: readonly SkillRef[],
+): SkillTriggerMatch[] {
+  const args = (call.args ?? {}) as { path?: unknown; command?: unknown }
+  const matches: SkillTriggerMatch[] = []
+  if (
+    typeof args.path === 'string' &&
+    (call.name === 'fs.read' || call.name === 'fs.write' || call.name === 'fs.patch')
+  ) {
+    for (const skill of skills) {
+      const fp = skill.frontmatter.filePattern
+      if (fp && matchFilePattern(fp, args.path)) {
+        matches.push({ skill, reason: 'filePattern' })
+      }
+    }
+  }
+  if (typeof args.command === 'string' && call.name === 'shell.run') {
+    for (const skill of skills) {
+      const bp = skill.frontmatter.bashPattern
+      if (bp && matchBashPattern(bp, args.command)) {
+        matches.push({ skill, reason: 'bashPattern' })
+      }
+    }
+  }
+  return matches
+}
+
+function globToRegex(glob: string): RegExp {
+  let pat = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*') pat += '.*'
+    else if (c === '?') pat += '.'
+    else if (c === '.') pat += '\\.'
+    else if (c === '/') pat += '/'
+    else pat += c
+  }
+  return new RegExp(`^${pat}$`)
+}