opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/lib/prompt-cache.mjs

@@ -5,30 +5,36 @@ function canonical(value) {
   if (!value || typeof value !== "object") return value
   return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]))
 }
-
-function stringify(value) {
-  return typeof value === "string" ? value : JSON.stringify(canonical(value))
-}
-
-function digest(value) {
-  return createHash("sha256").update(stringify(value)).digest("hex")
+function stringify(value) { return typeof value === "string" ? value : JSON.stringify(canonical(value)) }
+function digest(value) { return createHash("sha256").update(stringify(value)).digest("hex") }
+function chars(value) { return stringify(value ?? "").length }
+function finiteTokenCount(value) {
+  const number = Number(value)
+  return Number.isFinite(number) && number >= 0 ? number : null
 }
-
-function chars(value) {
-  return stringify(value ?? "").length
+function changedStableKeys(previous, current) {
+  const left = previous?.stable || {}
+  const right = current?.stable || {}
+  return [...new Set([...Object.keys(left), ...Object.keys(right)])]
+    .filter((key) => digest(left[key]) !== digest(right[key]))
+    .sort()
 }
 
 export function buildPromptEnvelope(input = {}) {
+  const memorySnapshot = input.memorySnapshot || null
   const stable = {
     invariants: input.invariants || "",
     role: input.role || "",
     skills: input.skills || [],
     projectFacts: input.projectFacts || {},
     toolPolicy: input.toolPolicy || {},
+    memorySnapshot,
   }
   const dynamic = {
     task: input.task || {},
     evidence: input.evidence || [],
+    memories: memorySnapshot ? [] : (input.memories || []),
+    contextHints: input.contextHints || {},
     recentFailure: input.recentFailure || null,
     nextAction: input.nextAction || null,
     recentMessages: input.recentMessages || [],
@@ -43,18 +49,28 @@ export function buildPromptEnvelope(input = {}) {
     dynamicHash: digest(dynamic),
     stableChars,
     dynamicChars,
+    cacheableChars: stableChars,
     cacheableRatio: stableChars + dynamicChars ? stableChars / (stableChars + dynamicChars) : 0,
+    cacheReadTokens: finiteTokenCount(input.cacheReadTokens),
+    cacheWriteTokens: finiteTokenCount(input.cacheWriteTokens),
   }
 }
 
-export function comparePromptEnvelopes(previous, current) {
+export function comparePromptEnvelopes(previous, current, usage = {}) {
   const stableReused = Boolean(previous?.stablePrefixHash && previous.stablePrefixHash === current?.stablePrefixHash)
   const repeatedStableChars = stableReused ? Number(current?.stableChars || 0) : 0
+  const mutated = stableReused ? [] : changedStableKeys(previous, current)
   return {
     schemaVersion: 1,
     stableReused,
     repeatedStableChars,
     avoidableRepeatedChars: stableReused ? 0 : Math.min(Number(previous?.stableChars || 0), Number(current?.stableChars || 0)),
     currentCacheableRatio: Number(current?.cacheableRatio || 0),
+    cacheableChars: Number(current?.cacheableChars ?? current?.stableChars ?? 0),
+    dynamicChars: Number(current?.dynamicChars || 0),
+    cacheReadTokens: finiteTokenCount(usage.cacheReadTokens ?? current?.cacheReadTokens),
+    cacheWriteTokens: finiteTokenCount(usage.cacheWriteTokens ?? current?.cacheWriteTokens),
+    prefixMutationReason: stableReused ? null : (mutated.length ? mutated.join(",") : "stable-prefix-changed"),
+    mutatedStableKeys: mutated,
   }
 }

package/lib/repo-graph.mjs

@@ -1,10 +1,12 @@
 import { readFile, readdir, stat } from "node:fs/promises"
 import path from "node:path"
+import { runtimeWorkspaceFingerprint } from "./workspace-fingerprint.mjs"
 
 const SKIP = new Set([
   ".git", "node_modules", ".next", "dist", "build", "coverage", ".venv", "venv",
-  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "bin", "obj",
-  ".ues-work",
+  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "obj",
+  ".ues-work", ".ues-cache", ".ues-traces", ".ues-learning", ".ues-dashboard",
+  ".ues-sandboxes", ".ues-memory", ".ues-evals",
 ])
 
 const SOURCE_EXTENSIONS = new Set([
@@ -133,3 +135,52 @@ export async function buildRepoGraph(root = process.cwd(), options = {}) {
       .slice(0, 50),
   }
 }
+
+const RUNTIME_GRAPH_CACHE = new Map()
+const RUNTIME_GRAPH_INFLIGHT = new Map()
+
+export async function buildRepoGraphCached(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const maxFiles = Number(options.maxFiles ?? 2500)
+  const maxDepth = Number(options.maxDepth ?? 8)
+  let fingerprint = String(options.workspaceFingerprint || "")
+  if (!fingerprint || fingerprint === "unknown") {
+    try {
+      fingerprint = runtimeWorkspaceFingerprint(root)
+    } catch {
+      return buildRepoGraph(root, options)
+    }
+  }
+  const key = [root, fingerprint, maxFiles, maxDepth].join("\u0000")
+  if (RUNTIME_GRAPH_CACHE.has(key)) {
+    const value = RUNTIME_GRAPH_CACHE.get(key)
+    RUNTIME_GRAPH_CACHE.delete(key)
+    RUNTIME_GRAPH_CACHE.set(key, value)
+    return value
+  }
+
+  if (RUNTIME_GRAPH_INFLIGHT.has(key)) {
+    return RUNTIME_GRAPH_INFLIGHT.get(key)
+  }
+
+  const pending = buildRepoGraph(root, options)
+  RUNTIME_GRAPH_INFLIGHT.set(key, pending)
+  let graph
+  try {
+    graph = await pending
+  } finally {
+    RUNTIME_GRAPH_INFLIGHT.delete(key)
+  }
+  RUNTIME_GRAPH_CACHE.set(key, graph)
+  while (RUNTIME_GRAPH_CACHE.size > 8) {
+    const oldest = RUNTIME_GRAPH_CACHE.keys().next().value
+    if (!oldest) break
+    RUNTIME_GRAPH_CACHE.delete(oldest)
+  }
+  return graph
+}
+
+export function clearRepoGraphRuntimeCache() {
+  RUNTIME_GRAPH_CACHE.clear()
+  RUNTIME_GRAPH_INFLIGHT.clear()
+}

package/lib/reversible-context.mjs

@@ -0,0 +1,49 @@
+import { putEvidence, getEvidence, getEvidenceSelected } from "./evidence-store.mjs"
+
+function normalize(value) { return String(value ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n") }
+function significantLines(text) {
+  const lines = normalize(text).split("\n")
+  const scored = lines.map((line, index) => {
+    const trimmed = line.trim(); let score = 0
+    if (/^#{1,6}\s/.test(trimmed)) score += 8
+    if (/^(?:[-*+] |\d+[.)]\s)/.test(trimmed)) score += 5
+    if (/\b(?:error|fail|warning|todo|fixme|pass|test|result|summary|important|must|required)\b/i.test(trimmed)) score += 4
+    if (/^(?:export|import|class|function|def|interface|type|CREATE|ALTER)\b/i.test(trimmed)) score += 3
+    if (trimmed.length > 0 && trimmed.length <= 180) score += 1
+    return { index, line, score }
+  })
+  return { lines, scored }
+}
+function summary(text, maxChars) {
+  const { lines, scored } = significantLines(text)
+  if (normalize(text).length <= maxChars) return normalize(text)
+  const wanted = new Set(scored.filter((row) => row.score > 0).sort((a,b) => b.score - a.score || a.index - b.index).slice(0,80).map((row) => row.index))
+  for (let i = Math.max(0, lines.length - 8); i < lines.length; i += 1) wanted.add(i)
+  let out = ""
+  for (const index of [...wanted].sort((a,b) => a-b)) {
+    const candidate = (out ? out + "\n" : "") + lines[index]
+    if (candidate.length > maxChars) break
+    out = candidate
+  }
+  return out || normalize(text).slice(0, maxChars)
+}
+export async function compactContext(root, content, options = {}) {
+  const raw = normalize(content)
+  const stored = await putEvidence(root, raw, { kind: options.kind || "context-block", source: options.source || "ues-context", summary: options.summary || "Reversible raw context block" })
+  return { schemaVersion: 1, ref: stored.ref, originalChars: raw.length, levels: { T1: summary(raw, Math.max(512, Number(options.t1Chars || 1600))), T2: summary(raw, Math.max(1200, Number(options.t2Chars || 5000))), T3: summary(raw, Math.max(2400, Number(options.t3Chars || 12000))) } }
+}
+export async function expandContext(root, ref, options = {}) {
+  return getEvidenceSelected(root, ref, { start: Math.max(0, Number(options.start || 0)), maxBytes: Math.max(1, Math.min(128_000, Number(options.maxBytes || 16_000))) })
+}
+export async function searchContext(root, ref, query, options = {}) {
+  const maxBytes = Math.max(16_000, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512_000)))
+  const evidence = await getEvidence(root, ref, { maxBytes })
+  const source = normalize(evidence?.content ?? evidence ?? "")
+  const terms = [...new Set(String(query || "").toLowerCase().split(/[^\p{L}\p{N}_$.-]+/u).filter((item) => item.length >= 2))].slice(0, 16)
+  const lines = source.split("\n"); const radius = Math.max(0, Math.min(12, Number(options.radius || 2))); const maxMatches = Math.max(1, Math.min(50, Number(options.maxMatches || 10))); const hits = []
+  for (let index = 0; index < lines.length && hits.length < maxMatches; index += 1) {
+    const lower = lines[index].toLowerCase(); const matched = terms.filter((term) => lower.includes(term)); if (!matched.length) continue
+    hits.push({ line: index + 1, terms: matched, excerpt: lines.slice(Math.max(0,index-radius), Math.min(lines.length,index+radius+1)).join("\n") })
+  }
+  return { schemaVersion: 1, ref, query: String(query || ""), terms, hits, truncatedSource: source.length >= maxBytes }
+}

package/lib/runtime-config.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+function xdgConfigRoot() {
+  return process.env.XDG_CONFIG_HOME
+    ? path.resolve(process.env.XDG_CONFIG_HOME)
+    : path.join(os.homedir(), ".config")
+}
+
+export function getUesConfigDir() {
+  if (process.env.UES_CONFIG_DIR) return path.resolve(process.env.UES_CONFIG_DIR)
+
+  const nativeDir = path.join(xdgConfigRoot(), "ues")
+  const legacyDir = process.env.OPENCODE_CONFIG_DIR
+    ? path.resolve(process.env.OPENCODE_CONFIG_DIR)
+    : path.join(xdgConfigRoot(), "opencode")
+
+  const nativePolicy = path.join(nativeDir, ".ues", "model-policy.json")
+  const legacyPolicy = path.join(legacyDir, ".ues", "model-policy.json")
+
+  if (existsSync(nativePolicy)) return nativeDir
+  if (existsSync(legacyPolicy)) return legacyDir
+  return nativeDir
+}
+
+export function getLegacyOpenCodeConfigDir() {
+  return process.env.OPENCODE_CONFIG_DIR
+    ? path.resolve(process.env.OPENCODE_CONFIG_DIR)
+    : path.join(xdgConfigRoot(), "opencode")
+}

package/lib/safety.mjs

@@ -0,0 +1,132 @@
+const RULES = [
+  { id: "git-force", pattern: /\bgit\s+(?:push\b[^\n]*(?:--force(?:-with-lease)?|(?:^|\s)-f(?:\s|$))|reset\s+--hard|clean\s+-[^\n]*f)/i },
+  { id: "history-rewrite", pattern: /\bgit\s+(?:rebase\b|filter-branch\b|filter-repo\b)/i },
+  { id: "publish", pattern: /\b(?:npm\s+publish|pnpm\s+publish|yarn\s+npm\s+publish)\b/i },
+  { id: "destructive-files", pattern: /(?:^|[;&|]\s*)(?:rm\s+-[^\n]*r[^\n]*f|rmdir\s+\/s|del\s+\/s|remove-item\b[^\n]*-recurse[^\n]*-force)/i },
+  { id: "database-drop", pattern: /\b(?:drop\s+(?:database|schema|table)|truncate\s+table)\b/i },
+  { id: "deployment", pattern: /\b(?:kubectl\s+(?:delete|apply)|terraform\s+(?:apply|destroy)|helm\s+(?:install|upgrade|uninstall))\b/i },
+]
+
+export function shellCommandSegments(command) {
+  const value = String(command || "")
+  const segments = []
+  let current = ""
+  let quote = null
+  let escaped = false
+  let depth = 0
+
+  const push = (operator = null) => {
+    const text = current.trim()
+    if (text) segments.push({ text, operator })
+    current = ""
+  }
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index]
+    const next = value[index + 1] || ""
+
+    if (escaped) {
+      current += char
+      escaped = false
+      continue
+    }
+    if (char === "\\" && quote !== "'") {
+      current += char
+      escaped = true
+      continue
+    }
+    if (quote) {
+      current += char
+      if (char === quote) quote = null
+      continue
+    }
+    if (char === "'" || char === '"') {
+      quote = char
+      current += char
+      continue
+    }
+    if (char === "(" || char === "{" || char === "[") {
+      depth += 1
+      current += char
+      continue
+    }
+    if (char === ")" || char === "}" || char === "]") {
+      depth = Math.max(0, depth - 1)
+      current += char
+      continue
+    }
+
+    if (depth === 0 && char === "&" && next === "&") {
+      push("&&")
+      index += 1
+      continue
+    }
+    if (depth === 0 && char === "|" && next === "|") {
+      push("||")
+      index += 1
+      continue
+    }
+    if (depth === 0 && (char === ";" || char === "|")) {
+      push(char)
+      continue
+    }
+    if (depth === 0 && char === "\n") {
+      push("\n")
+      continue
+    }
+    current += char
+  }
+  push(null)
+  return segments
+}
+
+export function destructiveShellAnalysis(command) {
+  const value = String(command || "")
+  const segments = shellCommandSegments(value)
+  const findings = []
+
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index]
+    for (const rule of RULES) {
+      // Clone regex state defensively if future rules add the global flag.
+      rule.pattern.lastIndex = 0
+      if (!rule.pattern.test(segment.text)) continue
+      findings.push({
+        id: rule.id,
+        segmentIndex: index,
+        segment: segment.text,
+        operator: segment.operator,
+      })
+      break
+    }
+  }
+
+  // Retain a whole-command fallback so nested shell syntax that the bounded
+  // splitter intentionally does not fully parse still fails closed.
+  if (!findings.length) {
+    for (const rule of RULES) {
+      rule.pattern.lastIndex = 0
+      if (rule.pattern.test(value)) {
+        findings.push({ id: rule.id, segmentIndex: null, segment: value, operator: null })
+        break
+      }
+    }
+  }
+
+  return {
+    risky: findings.length > 0,
+    id: findings[0]?.id || null,
+    findings,
+    segmentCount: segments.length,
+  }
+}
+
+export function destructiveShellRisk(command) {
+  const analysis = destructiveShellAnalysis(command)
+  return {
+    risky: analysis.risky,
+    id: analysis.id,
+    segmentIndex: analysis.findings[0]?.segmentIndex ?? null,
+    segment: analysis.findings[0]?.segment || null,
+  }
+}

package/lib/semantic-index.mjs

@@ -11,8 +11,8 @@ const SOURCE_EXTENSIONS = new Set([
 ])
 const SKIP_DIRS = new Set([
   ".git", "node_modules", ".next", "dist", "build", "coverage", ".venv", "venv",
-  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "bin", "obj",
-  ".ues-work", ".ues-learning", ".ues-dashboard", ".ues-sandboxes", ".ues-cache", ".ues-traces",
+  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "obj",
+  ".ues-work", ".ues-learning", ".ues-memory", ".ues-dashboard", ".ues-sandboxes", ".ues-cache", ".ues-traces",
 ])
 const STOP_IDENTIFIERS = new Set([
   "const","let","var","function","class","interface","type","export","import","from","return",
@@ -233,7 +233,7 @@ function queryTerms(query) {
 export async function querySemanticIndex(root, query, options = {}) {
   const terms = queryTerms(query)
   if (!terms.length) return { query: String(query || ""), terms: [], results: [], stats: null }
-  const built = await buildSemanticIndex(root, options)
+  const built = options.builtIndex || await buildSemanticIndex(root, options)
   const lowerTerms = terms.map((term) => term.toLowerCase())
   const results = []
 
@@ -316,3 +316,52 @@ export async function semanticIndexStatus(root = process.cwd()) {
     truncated: Boolean(cached?.truncated),
   }
 }
+
+const RUNTIME_SEMANTIC_CACHE = new Map()
+const RUNTIME_SEMANTIC_INFLIGHT = new Map()
+
+export async function buildSemanticIndexCached(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const fingerprint = String(options.workspaceFingerprint || "")
+  if (!fingerprint || fingerprint === "unknown") {
+    return buildSemanticIndex(root, options)
+  }
+
+  const maxFiles = Number(options.maxFiles ?? 6000)
+  const maxDepth = Number(options.maxDepth ?? 14)
+  const maxBytes = Number(options.maxBytes ?? 768 * 1024)
+  const key = [root, fingerprint, maxFiles, maxDepth, maxBytes].join("\u0000")
+  if (RUNTIME_SEMANTIC_CACHE.has(key)) {
+    const value = RUNTIME_SEMANTIC_CACHE.get(key)
+    RUNTIME_SEMANTIC_CACHE.delete(key)
+    RUNTIME_SEMANTIC_CACHE.set(key, value)
+    return { ...value, runtimeCacheHit: true }
+  }
+
+  if (RUNTIME_SEMANTIC_INFLIGHT.has(key)) {
+    const value = await RUNTIME_SEMANTIC_INFLIGHT.get(key)
+    return { ...value, runtimeCacheHit: true, runtimeCacheCoalesced: true }
+  }
+
+  const pending = buildSemanticIndex(root, options)
+    .then((built) => ({ ...built, runtimeCacheHit: false }))
+  RUNTIME_SEMANTIC_INFLIGHT.set(key, pending)
+
+  try {
+    const value = await pending
+    RUNTIME_SEMANTIC_CACHE.set(key, value)
+    while (RUNTIME_SEMANTIC_CACHE.size > 6) {
+      const oldest = RUNTIME_SEMANTIC_CACHE.keys().next().value
+      if (!oldest) break
+      RUNTIME_SEMANTIC_CACHE.delete(oldest)
+    }
+    return value
+  } finally {
+    RUNTIME_SEMANTIC_INFLIGHT.delete(key)
+  }
+}
+
+export function clearSemanticIndexRuntimeCache() {
+  RUNTIME_SEMANTIC_CACHE.clear()
+  RUNTIME_SEMANTIC_INFLIGHT.clear()
+}

package/lib/skill-compiler.mjs

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const SKILLS_ROOT = path.join(PACKAGE_ROOT, "global-config", "skills")
+const SKILL_SOURCE_CACHE = new Map()
+const COMPILED_SKILL_CACHE = new Map()
+
+const DOMAIN_SKILLS = Object.freeze({
+  "auth-security": "auth-security",
+  payment: "payment-engineering",
+  database: "database-engineering",
+  "api-contract": "api-contract",
+  "react-native": "react-native-engineering",
+  nextjs: "nextjs-engineering",
+  react: "react-engineering",
+  devops: "devops-engineering",
+})
+
+const ROLE_SKILLS = Object.freeze({
+  architect: ["software-architect", "task-planner"],
+  "codebase-mapper": ["repo-explorer", "context-engineering"],
+  critic: ["code-review", "change-impact-analysis"],
+  debugger: ["bug-diagnosis", "test-verification"],
+  executor: ["implementation-engineer"],
+  "integration-verifier": ["test-verification", "change-impact-analysis"],
+  "merge-arbiter": ["git-safety", "change-impact-analysis"],
+  "plan-checker": ["task-planner", "change-impact-analysis"],
+  researcher: ["research-verification"],
+  reviewer: ["code-review"],
+  verifier: ["test-verification"],
+  "visual-verifier": ["visual-fidelity", "responsive-verification", "browser-qa"],
+})
+
+function stripFrontmatter(raw) {
+  return String(raw || "").replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n/, "")
+}
+
+function priorityLine(line) {
+  return /^#{1,4}\s/.test(line) ||
+    /^[-*]\s+/.test(line) ||
+    /\b(must|never|always|verify|prefer|avoid|require|do not|don't|fail|evidence|security|safety|rollback|idempot|transaction|accessib)/i.test(line)
+}
+
+function compileText(raw, maxChars) {
+  const source = stripFrontmatter(raw)
+  const lines = source.split(/\r?\n/).map((line) => line.trimEnd())
+  const selected = []
+  let chars = 0
+
+  // Keep a short orientation prefix, then the highest-value rules/checklists.
+  for (const line of lines.slice(0, 20)) {
+    if (!line.trim()) continue
+    if (chars + line.length + 1 > Math.floor(maxChars * 0.35)) break
+    selected.push(line)
+    chars += line.length + 1
+  }
+  for (const line of lines) {
+    if (!line.trim() || !priorityLine(line) || selected.includes(line)) continue
+    if (chars + line.length + 1 > maxChars) break
+    selected.push(line)
+    chars += line.length + 1
+  }
+  return selected.join("\n").slice(0, maxChars)
+}
+
+export function selectSkillNames(taskPolicy = {}, role = "executor", options = {}) {
+  const maxSkills = Math.max(1, Math.min(5, Number(options.maxSkills || taskPolicy.maxSkills || 3)))
+  const names = []
+  for (const name of ROLE_SKILLS[role] || []) names.push(name)
+  for (const domain of taskPolicy.domains || []) {
+    const mapped = DOMAIN_SKILLS[domain]
+    if (mapped) names.push(mapped)
+  }
+  return [...new Set(names)].slice(0, maxSkills)
+}
+
+async function skillSource(name) {
+  if (SKILL_SOURCE_CACHE.has(name)) return SKILL_SOURCE_CACHE.get(name)
+  const file = path.join(SKILLS_ROOT, name, "SKILL.md")
+  if (!existsSync(file)) {
+    SKILL_SOURCE_CACHE.set(name, "")
+    return ""
+  }
+  const raw = await readFile(file, "utf8").catch(() => "")
+  SKILL_SOURCE_CACHE.set(name, raw)
+  return raw
+}
+
+export async function compileSkillContext(taskPolicy = {}, role = "executor", options = {}) {
+  const names = selectSkillNames(taskPolicy, role, options)
+  const totalChars = Math.max(800, Math.min(8_000, Number(options.totalChars || 3_200)))
+  const perSkill = Math.max(450, Math.floor(totalChars / Math.max(1, names.length)))
+  const cacheKey = JSON.stringify([role, names, totalChars, perSkill])
+  if (COMPILED_SKILL_CACHE.has(cacheKey)) {
+    return { ...COMPILED_SKILL_CACHE.get(cacheKey), cacheHit: true }
+  }
+
+  const skills = []
+  for (const name of names) {
+    const raw = await skillSource(name)
+    if (!raw) continue
+    const text = compileText(raw, perSkill)
+    if (text) skills.push({ name, text })
+  }
+
+  const result = {
+    schemaVersion: 1,
+    role,
+    requested: names,
+    loaded: skills.map((item) => item.name),
+    chars: skills.reduce((sum, item) => sum + item.text.length, 0),
+    text: skills
+      .map((item) => `### Skill: ${item.name}\n${item.text}`)
+      .join("\n\n")
+      .slice(0, totalChars),
+    cacheHit: false,
+  }
+  COMPILED_SKILL_CACHE.set(cacheKey, result)
+  return result
+}
+
+export function clearSkillCompilerCache() {
+  SKILL_SOURCE_CACHE.clear()
+  COMPILED_SKILL_CACHE.clear()
+}

package/lib/skill-quality.mjs

@@ -15,9 +15,53 @@ function similarity(a, b) {
   return union.size ? intersection / union.size : 0
 }
 
+export function validateFrontmatterSource(source, options = {}) {
+  const text = String(source || "")
+  const errors = []
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) {
+    return { valid: false, errors: [{ issue: "missing-frontmatter-open", file: options.file || null }] }
+  }
+
+  const match = text.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/)
+  if (!match) {
+    return { valid: false, errors: [{ issue: "missing-frontmatter-close", file: options.file || null }] }
+  }
+
+  const lines = match[1].split(/\r?\n/)
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (!line.trim() || /^\s/.test(line) || line.trimStart().startsWith("#")) continue
+    if (/\t/.test(line)) {
+      errors.push({ issue: "frontmatter-tab", line: index + 2, file: options.file || null })
+      continue
+    }
+    const field = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/)
+    if (!field) {
+      errors.push({ issue: "invalid-frontmatter-line", line: index + 2, file: options.file || null })
+      continue
+    }
+    const value = String(field[2] || "").trim()
+    if (!value) continue
+    const quoted = (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    const blockScalar = value === "|" || value === ">"
+    const flowValue = value.startsWith("[") || value.startsWith("{")
+    if (!quoted && !blockScalar && !flowValue && /:\s/.test(value)) {
+      errors.push({
+        issue: "unquoted-colon-in-scalar",
+        field: field[1],
+        line: index + 2,
+        file: options.file || null,
+      })
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
 function frontmatter(source) {
-  const name = source.match(/^name:\s*([^\r\n]+)/m)?.[1]?.trim() || null
-  const description = source.match(/^description:\s*([^\r\n]+)/m)?.[1]?.trim() || null
+  const name = source.match(/^name:\s*([^\r\n]+)/m)?.[1]?.trim()?.replace(/^(["'])(.*)\1$/, "$2") || null
+  const description = source.match(/^description:\s*([^\r\n]+)/m)?.[1]?.trim()?.replace(/^(["'])(.*)\1$/, "$2") || null
   return { name, description }
 }
 
@@ -36,6 +80,8 @@ export async function lintSkillCatalog(root = process.cwd(), options = {}) {
       continue
     }
     const source = await readFile(file, "utf8")
+    const yaml = validateFrontmatterSource(source, { file })
+    for (const error of yaml.errors) errors.push({ skill: entry.name, ...error })
     const meta = frontmatter(source)
     const body = source.replace(/^---[\s\S]*?---\s*/m, "")
     const row = {