@gpzhang2001/sharpkit-preset 0.2.1

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Pentest preset — the M3 prompt/knowledge layer: renders the strix system
+ * prompt (VERBATIM template + jinja-subset renderer + the skill selection
+ * policy) from scan configuration, registers it through the dsh
+ * system-prompt seam, and exposes scan-mode semantics (budget/turn
+ * defaults) as `pentestPreset` for the orchestrator. Golden-locked against
+ * renders from the original jinja template.
+ * @module @gpzhang2001/sharpkit-preset
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import { bundledSkillsRoot as skillsPackageRoot } from '@gpzhang2001/sharpkit-skills'
+import { renderTemplate } from './jinja.ts'
+import { getAvailableSkills, loadSkills, resolveSkills } from './skills.ts'
+
+export { renderTemplate } from './jinja.ts'
+export { getAvailableSkills, loadSkills, resolveSkills, validateRequestedSkills, parseSkillContent } from './skills.ts'
+
+/** The template file shipped verbatim from strix. */
+const TEMPLATE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'system_prompt.jinja'), 'utf8')
+
+/** Scan-mode budget semantics (manual §6 M3; orchestrator consumes). */
+export interface ScanModeSemantics {
+  readonly maxTurns: number
+  readonly maxBudgetUsd: number
+}
+
+/** The quick/deep budget matrix (initial values; M6 tunes). */
+const SCAN_MODE_SEMANTICS: Record<string, ScanModeSemantics> = {
+  quick: { maxTurns: 60, maxBudgetUsd: 5 },
+  deep: { maxTurns: 250, maxBudgetUsd: 25 },
+}
+
+/** Deployment-tunable configuration (cordis resolves defaults before apply). */
+export interface Config {
+  /** Scan mode: quick or deep. */
+  readonly scanMode?: string
+  /** Whether this agent is the root orchestrator. */
+  readonly isRoot?: boolean
+  /** Whether the scan has source access (whitebox). */
+  readonly isWhitebox?: boolean
+  /** Whether the session is interactive. */
+  readonly interactive?: boolean
+  /** Whether the scan is scoped to a change set. */
+  readonly isDiffScoped?: boolean
+  /** Requested skills (≤5, category-qualified). */
+  readonly skills?: readonly string[]
+  /** Scan targets rendered into the scope block. */
+  readonly authorizedTargets?: ReadonlyArray<{ readonly type: string; readonly value: string; readonly workspace_path?: string }>
+  readonly scopeSource?: string
+  readonly authorizationSource?: string
+  /** MCP connections rendered into the mcp block. */
+  readonly mcpConnections?: ReadonlyArray<{ readonly name: string; readonly tool_count: number; readonly purpose?: string }>
+  /** Skills tree root; defaults to the bundled pentest-suite skills. */
+  readonly skillsRoot?: string
+}
+
+export const name = 'pentest-preset'
+
+export const inject: string[] = []
+
+export const Config: Schema<Config> = z.object({
+  scanMode: z.string().default('deep'),
+  isRoot: z.boolean().default(true),
+  isWhitebox: z.boolean().default(false),
+  interactive: z.boolean().default(true),
+  isDiffScoped: z.boolean().default(false),
+  skills: z.array(z.string()),
+  authorizedTargets: z.array(z.object({
+    type: z.string(),
+    value: z.string(),
+    workspace_path: z.string(),
+  })),
+  scopeSource: z.string(),
+  authorizationSource: z.string(),
+  mcpConnections: z.array(z.object({
+    name: z.string(),
+    tool_count: z.number(),
+    purpose: z.string(),
+  })),
+  skillsRoot: z.string(),
+}) as unknown as Schema<Config>
+
+/** Default skills root: the skills package's bundled corpus (npm-layout safe). */
+export function bundledSkillsRoot(): string {
+  return skillsPackageRoot()
+}
+
+/**
+ * Render the system prompt for one configuration (pure given the inputs).
+ * @param config - resolved preset config.
+ * @returns the rendered markdown prompt.
+ */
+export function renderPresetPrompt(config: Config): string {
+  const skillsRoot = config.skillsRoot ?? bundledSkillsRoot()
+  const requested = config.skills ?? []
+  const skillNames = resolveSkills({
+    requested,
+    scanMode: config.scanMode ?? 'deep',
+    isRoot: config.isRoot ?? true,
+    isWhitebox: config.isWhitebox ?? false,
+    isDiffScoped: config.isDiffScoped ?? false,
+  })
+  const skillContent = loadSkills(skillNames, skillsRoot)
+  const targets = (config.authorizedTargets ?? []).map(target => ({ ...target }))
+  const hasScope = targets.length > 0 || config.scopeSource !== undefined
+  const mcpConnections = (config.mcpConnections ?? []).map(connection => ({ ...connection }))
+  return renderTemplate(TEMPLATE, {
+    is_root: config.isRoot ?? true,
+    interactive: config.interactive ?? true,
+    loaded_skill_names: [...Object.keys(skillContent)],
+    available_skills: getAvailableSkills(skillsRoot),
+    get_skill: (name: string): string => skillContent[name] ?? '',
+    system_prompt_context: {
+      ...(hasScope ? { authorized_targets: targets, scope_source: config.scopeSource, authorization_source: config.authorizationSource } : {}),
+      ...(config.mcpConnections !== undefined && config.mcpConnections.length > 0 ? { mcp_available: true, mcp_connections: mcpConnections } : {}),
+    },
+    ...skillContent,
+  })
+}
+
+/** Scan-mode semantics lookup (quick default when the mode is unknown). */
+export function scanModeSemantics(scanMode: string): ScanModeSemantics {
+  return SCAN_MODE_SEMANTICS[scanMode] ?? { maxTurns: 60, maxBudgetUsd: 5 }
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const prompt = renderPresetPrompt(config)
+  // The persona section exists on host compositions; the headless one-shot
+  // tree mounts no system-prompt service, where the preset still provides
+  // pentestPreset (the rendered text is available to SDK consumers).
+  void ctx.inject(['systemPrompt'], (promptCtx: unknown) => {
+    ;(promptCtx as Context).systemPrompt.section({
+      // PERSONA_SECTION is the slot an agent preset shadows (system-prompt docs).
+      name: 'deployment:persona',
+      order: (promptCtx as Context).systemPrompt.getSectionOrder('DEPLOYMENT_PERSONA'),
+      text: prompt,
+    })
+  })
+  ctx.provide('pentestPreset', {
+    scanMode: config.scanMode ?? 'deep',
+    isRoot: config.isRoot ?? true,
+    ...scanModeSemantics(config.scanMode ?? 'deep'),
+    /** Consumed by tool-proxy's repeat_request target enforcement. */
+    authorizedTargets: (config.authorizedTargets ?? []).map(target => ({ ...target })),
+  })
+}
+

package/src/jinja.ts

@@ -0,0 +1,298 @@
+/**
+ * A minimal Jinja-subset renderer covering exactly the constructs the
+ * strix system prompt template uses: line-level {% if %}/{% else %}/
+ * {% endif %}/{% for x in y %}/{% endfor %}, inline {% if %}...{% endif %},
+ * and {{ dotted.expr }} interpolation (with `a and b` truthiness and the
+ * `available_skills | dictsort` filter). The template file ships VERBATIM
+ * from strix — no hand transcription — and whitespace semantics follow
+ * default Jinja (a lone tag line renders as an empty line).
+ * @module @gpzhang2001/sharpkit-preset/jinja
+ */
+
+/** A rendered value: strings, numbers, booleans, null, arrays, objects. */
+export type JinjaValue = string | number | boolean | null | JinjaValue[] | { [key: string]: JinvaRecordValue } | JinvaRecordValue[]
+type JinvaRecordValue = string | number | boolean | null | JinvaRecordValue[] | { [key: string]: JinvaRecordValue }
+
+/** Truthiness per Jinja: undefined/null/false/empty string/empty array are falsy. */
+function isTruthy(value: unknown): boolean {
+  if (value === undefined || value === null || value === false) return false
+  if (typeof value === 'string') return value !== ''
+  if (Array.isArray(value)) return value.length > 0
+  return true
+}
+
+/** Resolve a dotted path — or a zero/one-arg call like get_skill(x) — against the scope chain. */
+function lookup(scopes: ReadonlyArray<Record<string, unknown>>, path: string): unknown {
+  const call = /^([^(]+)\(([^)]*)\)$/.exec(path)
+  if (call !== null) {
+    const fn = resolveName(scopes, (call[1] ?? '').trim())
+    if (typeof fn !== 'function') return undefined
+    const argExpression = (call[2] ?? '').trim()
+    const arg = argExpression === '' ? undefined : lookup(scopes, argExpression)
+    return (fn as (value?: unknown) => unknown)(arg)
+  }
+  return resolveName(scopes, path)
+}
+
+/** Resolve a dotted name against a scope chain (top of stack first). */
+function resolveName(scopes: ReadonlyArray<Record<string, unknown>>, path: string): unknown {
+  const parts = path.split('.')
+  const head = parts[0] ?? ''
+  const rest = parts.slice(1)
+  for (let index = scopes.length - 1; index >= 0; index--) {
+    const scope = scopes[index]
+    if (scope === undefined || !(head in scope)) continue
+    let current: unknown = scope[head]
+    for (const part of rest) {
+      if (typeof current !== 'object' || current === null) return undefined
+      current = (current as Record<string, unknown>)[part]
+    }
+    return current
+  }
+  return undefined
+}
+
+/** Evaluate one condition expression: `a`, `a.b`, `x and y`. */
+function evaluateCondition(scopes: ReadonlyArray<Record<string, unknown>>, expression: string): boolean {
+  const conjuncts = expression.split(' and ').map(part => part.trim())
+  return conjuncts.every(part => isTruthy(lookup(scopes, part)))
+}
+
+/** Interpolate {{ expr }} occurrences (dotted lookup; undefined renders as empty per strix usage guard). */
+function interpolate(scopes: ReadonlyArray<Record<string, unknown>>, text: string): string {
+  return text.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, expression: string) => {
+    const value = lookup(scopes, expression.trim())
+    return value === undefined || value === null ? '' : String(value)
+  })
+}
+
+/** dictsort: sort object entries by key (jinja dictsort default). */
+function dictSort(value: unknown): Array<{ key: string; value: unknown }> {
+  if (typeof value !== 'object' || value === null) return []
+  return Object.entries(value as Record<string, unknown>)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, entryValue]) => ({ key, value: entryValue }))
+}
+
+/** One parsed template directive. */
+type Line =
+  | { readonly kind: 'text'; readonly text: string }
+  | { readonly kind: 'if'; readonly condition: string }
+  | { readonly kind: 'else' }
+  | { readonly kind: 'endif' }
+  | { readonly kind: 'for'; readonly variable: string; readonly iterable: string; readonly rightTrim: boolean }
+  | { readonly kind: 'endfor' }
+
+/** Parse template text into lines, splitting inline {% if %}/{% endif %} fragments. */
+function parseLines(text: string): Line[] {
+  const lines: Line[] = []
+  for (const rawLine of text.split('\n')) {
+    // Line-alone block tags take precedence over inline-fragment splitting.
+    const trimmed = rawLine.trim()
+    const loneIf = /^\{%-?\s*if\s+(.+?)\s*-?%\}$/.exec(trimmed)
+    const loneElse = /^\{%-?\s*else\s*-?%\}$/.test(trimmed)
+    const loneEndif = /^\{%-?\s*endif\s*-?%\}$/.test(trimmed)
+    const loneFor = /^\{%-?\s*for\s+(.+?)\s*-?%\}$/.exec(trimmed)
+    const loneEndfor = /^\{%-?\s*endfor\s*-?%\}$/.test(trimmed)
+    if (loneIf !== null) {
+      lines.push({ kind: 'if', condition: loneIf[1] ?? '' })
+      continue
+    }
+    if (loneElse) {
+      lines.push({ kind: 'else' })
+      continue
+    }
+    if (loneEndif) {
+      lines.push({ kind: 'endif' })
+      continue
+    }
+    if (loneFor !== null) {
+      const rightTrim = loneFor[0].endsWith('-%}')
+      const declaration = loneFor[1] ?? ''
+      const two = /^(\w+),\s*(\w+)\s+in\s+(.+?)\s*\|\s*(\w+)$/.exec(declaration)
+      const one = /^(\w+)\s+in\s+(.+?)\s*\|\s*(\w+)$/.exec(declaration)
+      const onePlain = /^(\w+)\s+in\s+(.+?)$/.exec(declaration)
+      if (two !== null) {
+        lines.push({ kind: 'for', variable: `${two[1]},${two[2]}`, iterable: `${two[3]}|${two[4] ?? ''}`, rightTrim })
+      } else if (one !== null) {
+        lines.push({ kind: 'for', variable: one[1] ?? '', iterable: `${one[2] ?? ''}|${one[3] ?? ''}`, rightTrim })
+      } else if (onePlain !== null) {
+        lines.push({ kind: 'for', variable: onePlain[1] ?? '', iterable: onePlain[2] ?? '', rightTrim })
+      }
+      continue
+    }
+    if (loneEndfor) {
+      lines.push({ kind: 'endfor' })
+      continue
+    }
+    const inlineParts = rawLine.split(/(\{%-?\s*(?:if|endif)\s+[^%]*?-?%\}|\{\{-?[^-]*?-?\}\})/g)
+    if (inlineParts.length > 1 && inlineParts.some(part => part.includes('{%'))) {
+      // A line mixing text and inline if/endif tags: expand into sub-lines
+      // while preserving the join (rendered pieces re-join with '').
+      let buffer = ''
+      const segments: Array<{ readonly tag: string | null; readonly text: string }> = []
+      for (const part of inlineParts) {
+        const ifMatch = /^\{%-?\s*if\s+(.+?)\s*-?%\}$/.exec(part)
+        const endifMatch = /^\{%-?\s*endif\s*-?%\}$/.exec(part)
+        if (ifMatch !== null) {
+          if (buffer !== '') segments.push({ tag: null, text: buffer })
+          buffer = ''
+          segments.push({ tag: `if ${ifMatch[1]}`, text: '' })
+        } else if (endifMatch !== null) {
+          if (buffer !== '') segments.push({ tag: null, text: buffer })
+          buffer = ''
+          segments.push({ tag: 'endif', text: '' })
+        } else {
+          buffer += part
+        }
+      }
+      if (buffer !== '') segments.push({ tag: null, text: buffer })
+      // Emit as a synthetic single line handled by renderSegments.
+      lines.push({ kind: 'text', text: `\u0000SEG${JSON.stringify(segments)}\u0000` })
+      continue
+    }
+    const ifMatch = /^\{%-?\s*if\s+(.+?)\s*-?%\}$/.exec(rawLine.trim())
+    if (ifMatch !== null) {
+      lines.push({ kind: 'if', condition: ifMatch[1] ?? '' })
+      continue
+    }
+    if (/^\{%-?\s*else\s*-?%\}$/.test(rawLine.trim())) {
+      lines.push({ kind: 'else' })
+      continue
+    }
+    if (/^\{%-?\s*endif\s*-?%\}$/.test(rawLine.trim())) {
+      lines.push({ kind: 'endif' })
+      continue
+    }
+    lines.push({ kind: 'text', text: rawLine })
+  }
+  return lines
+}
+
+/** Render segment-marked text lines (inline if fragments). */
+function renderSegments(text: string, scopes: ReadonlyArray<Record<string, unknown>>): string {
+  const payload = text.slice(4, -1)
+  const segments = JSON.parse(payload) as Array<{ tag: string | null; text: string }>
+  let out = ''
+  let include = true
+  for (const segment of segments) {
+    if (segment.tag !== null) {
+      include = segment.tag.startsWith('if') ? evaluateCondition(scopes, segment.tag.slice(3)) : false
+      continue
+    }
+    if (include) out += interpolate(scopes, segment.text)
+  }
+  return out
+}
+
+/**
+ * Render the template text with a variable scope.
+ * @param template - the raw jinja template text.
+ * @param variables - top-level template variables.
+ * @returns the rendered output.
+ */
+export function renderTemplate(template: string, variables: Record<string, unknown>): string {
+  const scopes: Record<string, unknown>[] = [variables]
+  // Jinja default keep_trailing_newline=False: the template's final newline
+  // is removed before rendering.
+  const lines = parseLines(template.replace(/\n$/, ''))
+  const output: string[] = []
+  // Block stack for if/for with instruction pointers.
+  const emit = (from: number, to: number): void => {
+    let index = from
+    while (index < to) {
+      const line = lines[index]
+      index++
+      if (line === undefined) break
+      if (line.kind === 'text') {
+        output.push(line.text.startsWith('\u0000SEG') ? renderSegments(line.text, scopes) : interpolate(scopes, line.text))
+        continue
+      }
+      if (line.kind === 'if') {
+        const taken = evaluateCondition(scopes, line.condition)
+        // Find matching else/endif at the same depth.
+        let depth = 0
+        let elseAt = -1
+        let endifAt = -1
+        let cursor = index
+        while (cursor < to) {
+          const probe = lines[cursor]
+          if (probe?.kind === 'if') depth++
+          if (probe?.kind === 'endif') {
+            if (depth === 0) {
+              endifAt = cursor
+              break
+            }
+            depth--
+          }
+          if (probe?.kind === 'else' && depth === 0 && elseAt === -1) elseAt = cursor
+          cursor++
+        }
+        if (endifAt === -1) endifAt = to
+        // Jinja default whitespace: a block tag adjacent to the TAKEN side
+        // keeps its line's newline (renders as one empty line); everything
+        // inside a FALSE region — including its opening tag — vanishes,
+        // except the closing endif, which always leaves one blank line.
+        if (taken) {
+          output.push('')
+          emit(index, elseAt === -1 ? endifAt : elseAt)
+        } else if (elseAt !== -1) {
+          // The else tag's trailing newline belongs to the taken side.
+          output.push('')
+          emit(elseAt + 1, endifAt)
+        }
+        output.push('')
+        index = endifAt + 1
+        continue
+      }
+      if (line.kind === 'for') {
+        const [iterableSource, filter = ''] = line.iterable.split('|')
+        const raw = lookup(scopes, iterableSource ?? '')
+        void filter
+        // Find endfor at the same depth.
+        let depth = 0
+        let endforAt = to
+        let cursor = index
+        while (cursor < to) {
+          const probe = lines[cursor]
+          if (probe?.kind === 'for') depth++
+          if (probe?.kind === 'endfor') {
+            if (depth === 0) {
+              endforAt = cursor
+              break
+            }
+            depth--
+          }
+          cursor++
+        }
+        const [nameA, nameB] = line.variable.split(',')
+        const items: Array<{ readonly key: string; readonly value: unknown }> = nameB !== undefined && nameA !== undefined
+          ? dictSort(raw)
+          : (Array.isArray(raw) ? raw : []).map(item => ({ key: '', value: item }))
+        if (items.length > 0) {
+          for (const entry of items) {
+            // The for tag's trailing newline is INSIDE the loop body (default
+            // Jinja); `-%}` right-trims it away for every iteration.
+            if (!line.rightTrim) output.push('')
+            if (nameB !== undefined && nameA !== undefined) {
+              const scope: Record<string, unknown> = {}
+              scope[nameA] = entry.key
+              scope[nameB] = entry.value
+              scopes.push(scope)
+            } else {
+              scopes.push({ [line.variable]: entry.value })
+            }
+            emit(index, endforAt)
+            scopes.pop()
+          }
+          if (!line.rightTrim) output.push('')
+        }
+        index = endforAt + 1
+        continue
+      }
+    }
+  }
+  emit(0, lines.length)
+  return output.join('\n')
+}
+

package/src/skills.ts

@@ -0,0 +1,172 @@
+/**
+ * Skill resolution — port of strix skills/__init__.py `_resolve_skills`,
+ * `load_skills`, `get_available_skills`, and `validate_requested_skills`
+ * over a filesystem skills root with the `<root>/<category>/<name>.md`
+ * layout (the bundled pentest-suite skills tree, or the strix original for
+ * golden tests).
+ * @module @gpzhang2001/sharpkit-preset/skills
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Internal categories excluded from the selectable catalog (strix parity). */
+const INTERNAL_SKILL_CATEGORIES = new Set(['scan_modes', 'coordination', 'analysis'])
+
+/** Frontmatter regex (strix `_FRONTMATTER_PATTERN`). */
+const FRONTMATTER = /^---\s*\n([\s\S]*?)\n---\s*\n/
+
+/** Parsed skill metadata + body. */
+export interface SkillFile {
+  readonly metadata: Record<string, string>
+  readonly body: string
+}
+
+/** Parse frontmatter and body (strix `_parse_skill_content`). */
+export function parseSkillContent(content: string): SkillFile {
+  const match = FRONTMATTER.exec(content)
+  if (match === null) return { metadata: {}, body: content.replace(/^\s+/, '') }
+  const body = match[1] ?? ''
+  const metadata: Record<string, string> = {}
+  for (const line of body.split('\n')) {
+    const colon = line.indexOf(':')
+    if (colon === -1) continue
+    const key = line.slice(0, colon).trim()
+    let value = line.slice(colon + 1).trim()
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1)
+    if (value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1)
+    metadata[key] = value
+  }
+  const rest = content.slice(match[0].length)
+  return { metadata, body: rest.replace(/^\s+/, '') }
+}
+
+/** One selectable skill in the catalog. */
+export interface SkillCatalogEntry {
+  readonly category: string
+  readonly name: string
+  readonly description: string
+}
+
+/**
+ * List selectable skills (strix `_iter_user_skill_files` + frontmatter):
+ * root-level `*.md` plus category directories, excluding internal
+ * categories from the catalog.
+ * @param skillsRoot - the skills tree root.
+ */
+export function getAvailableSkills(skillsRoot: string): Record<string, Array<{ name: string; description: string }>> {
+  const grouped: Record<string, Array<{ name: string; description: string }>> = {}
+  if (!existsSync(skillsRoot)) return grouped
+  const seen = new Set<string>()
+  const consider = (category: string, name: string): void => {
+    const key = `${category}/${name}`
+    if (seen.has(key)) return
+    const path = category === 'root' ? join(skillsRoot, `${name}.md`) : join(skillsRoot, category, `${name}.md`)
+    if (!existsSync(path)) return
+    const { metadata } = parseSkillContent(readFileSync(path, 'utf8'))
+    const description = (metadata['description'] ?? '').split(/\s+/).filter(Boolean).join(' ')
+    grouped[category] ??= []
+    grouped[category]?.push({ name, description })
+    seen.add(key)
+  }
+  const entries = readdirSync(skillsRoot, { withFileTypes: true })
+  const rootFiles = entries.filter(entry => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('__') && entry.name !== 'README.md').map(entry => entry.name).sort()
+  for (const name of rootFiles) consider('root', name.replace(/\.md$/, ''))
+  const categoryDirs = entries.filter(entry => entry.isDirectory() && !entry.name.startsWith('__')).map(entry => entry.name).sort()
+  for (const category of categoryDirs) {
+    if (INTERNAL_SKILL_CATEGORIES.has(category)) continue
+    const files = readdirSync(join(skillsRoot, category)).filter(name => name.endsWith('.md')).sort()
+    for (const file of files) consider(category, file.replace(/\.md$/, ''))
+  }
+  return grouped
+}
+
+/**
+ * Resolve the deduped, ordered skills list (strix `_resolve_skills`).
+ * @param options - requested skills and the shape flags.
+ */
+export function resolveSkills(options: {
+  readonly requested?: readonly string[]
+  readonly scanMode: string
+  readonly isRoot: boolean
+  readonly isWhitebox: boolean
+  readonly isDiffScoped: boolean
+}): string[] {
+  const ordered: string[] = [...(options.requested ?? [])]
+  ordered.push(`scan_modes/${options.scanMode}`)
+  if (options.isDiffScoped) ordered.push('scan_modes/diff')
+  ordered.push('tooling/agent_browser')
+  ordered.push('tooling/python')
+  ordered.push('analysis/counterevidence')
+  ordered.push('analysis/severity_calibration')
+  if (options.isRoot) ordered.push('coordination/root_agent')
+  if (options.isWhitebox) {
+    ordered.push('coordination/source_aware_whitebox')
+    ordered.push('custom/source_aware_sast')
+    ordered.push('analysis/source_aware_discovery')
+    ordered.push('analysis/fix_verification')
+  }
+  const deduped: string[] = []
+  const seen = new Set<string>()
+  for (const skill of ordered) {
+    if (skill !== '' && !seen.has(skill)) {
+      deduped.push(skill)
+      seen.add(skill)
+    }
+  }
+  return deduped
+}
+
+/**
+ * Load skill bodies keyed by their BARE names (strix `load_skills` returns
+ * {'deep': ...}, not {'scan_modes/deep': ...} — the `<skill_name>` tags in
+ * the prompt use bare names). Missing skills resolve to ''.
+ * @param names - qualified skill names (category/name).
+ * @param skillsRoot - the skills tree root.
+ */
+export function loadSkills(names: readonly string[], skillsRoot: string): Record<string, string> {
+  const content: Record<string, string> = {}
+  for (const name of names) {
+    const [category, fileName] = name.split('/')
+    if (category === undefined || fileName === undefined) {
+      content[name] = ''
+      continue
+    }
+    const path = join(skillsRoot, category, `${fileName}.md`)
+    if (existsSync(path)) content[fileName] = parseSkillContent(readFileSync(path, 'utf8')).body
+  }
+  return content
+}
+
+/**
+ * Validate a requested skill list (strix `validate_requested_skills`).
+ * @param skillList - the requested names.
+ * @param skillsRoot - the skills tree root.
+ * @returns an error message, or null when valid.
+ */
+export function validateRequestedSkills(skillList: readonly string[], skillsRoot: string, maxSkills = 5): string | null {
+  if (skillList.length > maxSkills) {
+    return `Cannot specify more than ${String(maxSkills)} skills per agent; got ${String(skillList.length)}. Aim for 1-3 related skills per specialist.`
+  }
+  if (skillList.length === 0) return null
+  const catalog = getAvailableSkills(skillsRoot)
+  const availableNames = new Set(Object.values(catalog).flat().map(entry => entry.name))
+  const availableKeys = new Set(Object.entries(catalog).flatMap(([category, entries]) => entries.map(entry => `${category}/${entry.name}`)))
+  const invalid = [...new Set(skillList.filter(skill => !availableNames.has(skill) && !availableKeys.has(skill)))].sort()
+  if (invalid.length > 0) {
+    return `Invalid skill name(s): ${JSON.stringify(invalid)}. Available skills: ${JSON.stringify(Object.values(catalog).flat().map(entry => entry.name).sort())}`
+  }
+  const ambiguousNames = new Set<string>()
+  const nameCounts = new Map<string, number>()
+  for (const entries of Object.values(catalog)) {
+    for (const entry of entries) nameCounts.set(entry.name, (nameCounts.get(entry.name) ?? 0) + 1)
+  }
+  for (const [name, count] of nameCounts) {
+    if (count > 1) ambiguousNames.add(name)
+  }
+  const ambiguous = skillList.filter(skill => !skill.includes('/') && ambiguousNames.has(skill)).sort()
+  if (ambiguous.length > 0) {
+    return `Ambiguous skill name(s): ${JSON.stringify(ambiguous)}. Use category-qualified names from: ${JSON.stringify([...availableKeys].sort())}`
+  }
+  return null
+}