feat(bootstrap): move skill catalog into system prompt (#365)

* docs(plans): add bootstrap message0 skill catalog plan

* feat(skills): add systematic skill catalog helper

* feat(bootstrap): canonicalize bootstrap in first system message

* feat(bootstrap): include bundled skill catalog

* feat(skill-tool): use compact skill catalog fallback

* fix(bootstrap): preserve malformed marker fragments

* test(skills): organize skill catalog imports

* fix(bootstrap): address catalog review feedback

Author: marcusrbrown

docs/plans/2026-05-13-001-feat-bootstrap-message0-skill-catalog-plan.md

@@ -3,6 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import type { SystematicConfig } from './config.js'
 import { parseFrontmatter } from './frontmatter.js'
+import { renderCatalogVerbose } from './skill-catalog.js'
 
 // Signatures used to identify OpenCode internal agents (title generator,
 // summarizer, etc.) so bootstrap injection can be skipped. Exported for
@@ -20,21 +21,66 @@ const BOOTSTRAP_MARKER_CLOSE = '</SYSTEMATIC_WORKFLOWS>'
 
 const findBootstrapMarkerBlock = (
   entry: string,
-): { start: number; end: number } | null => {
-  const start = entry.indexOf(BOOTSTRAP_MARKER_OPEN)
+  fromIndex = 0,
+): { start: number; closeStart: number; end: number } | null => {
+  const start = entry.indexOf(BOOTSTRAP_MARKER_OPEN, fromIndex)
   if (start === -1) return null
   const closeStart = entry.indexOf(
     BOOTSTRAP_MARKER_CLOSE,
     start + BOOTSTRAP_MARKER_OPEN.length,
   )
   if (closeStart === -1) return null
-  return { start, end: closeStart + BOOTSTRAP_MARKER_CLOSE.length }
+  return { start, closeStart, end: closeStart + BOOTSTRAP_MARKER_CLOSE.length }
+}
+
+const removeCompleteBootstrapBlocks = (entry: string): string => {
+  const segments: string[] = []
+  let cursor = 0
+  let block = findBootstrapMarkerBlock(entry, cursor)
+  let hadNestedBlock = false
+
+  while (block !== null) {
+    const nestedStart = entry.indexOf(
+      BOOTSTRAP_MARKER_OPEN,
+      block.start + BOOTSTRAP_MARKER_OPEN.length,
+    )
+
+    if (nestedStart !== -1 && nestedStart < block.closeStart) {
+      hadNestedBlock = true
+      segments.push(entry.slice(cursor, nestedStart))
+      cursor = nestedStart
+      block = findBootstrapMarkerBlock(entry, cursor)
+      continue
+    }
+
+    segments.push(entry.slice(cursor, block.start))
+    cursor = block.end
+    block = findBootstrapMarkerBlock(entry, cursor)
+  }
+
+  if (cursor === 0) return entry
+  segments.push(entry.slice(cursor))
+  const result = segments.join('')
+
+  // When nested blocks are removed, previously truncated outer open/close
+  // markers may now form a complete block. Recurse once to clean up in a
+  // single call rather than requiring a second transform invocation.
+  if (hadNestedBlock) {
+    return removeCompleteBootstrapBlocks(result)
+  }
+
+  return result
 }
 
 /**
- * Inject bootstrap content into the system prompt array, replacing any
- * existing `<SYSTEMATIC_WORKFLOWS>` block. Multi-load idempotency is via
- * the marker — most-recently-registered plugin wins under FIFO hook order.
+ * Inject bootstrap content into the system prompt array, placing exactly one
+ * canonical block at the end of `output.system[0]`.
+ *
+ * All complete `<SYSTEMATIC_WORKFLOWS>…</SYSTEMATIC_WORKFLOWS>` blocks are
+ * removed from every system entry first, then the current content is appended
+ * once to `output.system[0]`. Partial/malformed marker fragments are left
+ * untouched. This makes duplicate registration and prior last-entry placement
+ * converge to the new canonical location; later invocations win.
  *
  * Exported for test access — must NOT be re-exported from the plugin entry
  * point (src/index.ts) because OpenCode's plugin loader expects a single
@@ -45,20 +91,18 @@ export const applyBootstrapContent = (
   output: { system: string[] },
   content: string,
 ): void => {
+  // Remove every complete marker block from every entry.
   for (let i = 0; i < output.system.length; i++) {
-    const entry = output.system[i]
-    const block = findBootstrapMarkerBlock(entry)
-    if (block !== null) {
-      output.system[i] =
-        entry.slice(0, block.start) + content + entry.slice(block.end)
-      return
-    }
+    output.system[i] = removeCompleteBootstrapBlocks(output.system[i])
   }
-  if (output.system.length > 0) {
-    output.system[output.system.length - 1] += `\n\n${content}`
-  } else {
+
+  if (output.system.length === 0) {
     output.system.push(content)
+    return
   }
+
+  const first = output.system[0]
+  output.system[0] = first.length > 0 ? `${first}\n\n${content}` : content
 }
 
 export interface BootstrapDeps {
@@ -113,6 +157,11 @@ export function getBootstrapContent(
   const { body } = parseFrontmatter(fullContent)
   const content = body.trim()
   const toolMapping = getToolMappingTemplate()
+  const catalog = renderCatalogVerbose({
+    bundledSkillsDir,
+    disabledSkills: config.disabled_skills,
+  })
+  const catalogSection = catalog.length > 0 ? `\n\n${catalog}` : ''
 
   return `<SYSTEMATIC_WORKFLOWS>
 You have access to structured engineering workflows via the systematic plugin.
@@ -121,6 +170,6 @@ You have access to structured engineering workflows via the systematic plugin.
 
 ${content}
 
-${toolMapping}
+${toolMapping}${catalogSection}
 </SYSTEMATIC_WORKFLOWS>`
 }

src/lib/bootstrap.ts

@@ -0,0 +1,86 @@
+import { pathToFileURL } from 'node:url'
+import { formatSkillCommandName } from './skill-loader.js'
+import { findSkillsInDir } from './skills.js'
+
+/**
+ * Escape XML special characters (&, <, >) in text content.
+ * Quotes are not escaped because catalog names and descriptions are rendered
+ * as element text, not attribute values.
+ */
+export function escapeXml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+export interface CatalogEntry {
+  name: string
+  prefixedName: string
+  description: string
+  path: string
+  skillFile: string
+}
+
+export interface CatalogOptions {
+  bundledSkillsDir: string
+  disabledSkills: string[]
+}
+
+/**
+ * Discovers and filters bundled Systematic skills into catalog entries.
+ * Excludes disabled skills and skills with disableModelInvocation === true.
+ * Returns entries sorted by name.
+ */
+export function buildCatalogEntries(options: CatalogOptions): CatalogEntry[] {
+  const { bundledSkillsDir, disabledSkills } = options
+
+  return findSkillsInDir(bundledSkillsDir)
+    .filter((s) => !disabledSkills.includes(s.name))
+    .filter((s) => s.disableModelInvocation !== true)
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((s) => ({
+      name: s.name,
+      prefixedName: formatSkillCommandName(s.name),
+      description: s.description,
+      path: s.path,
+      skillFile: s.skillFile,
+    }))
+}
+
+/**
+ * Renders discoverable skills as native-style verbose XML for bootstrap content.
+ * Returns empty string when no skills are available.
+ */
+export function renderCatalogVerbose(options: CatalogOptions): string {
+  const entries = buildCatalogEntries(options)
+
+  if (entries.length === 0) return ''
+
+  const skillLines = entries.flatMap((entry) => [
+    '  <skill>',
+    `    <name>${escapeXml(entry.prefixedName)}</name>`,
+    `    <description>${escapeXml(entry.description)}</description>`,
+    `    <location>${pathToFileURL(entry.path).href}</location>`,
+    '  </skill>',
+  ])
+
+  return ['<available_skills>', ...skillLines, '</available_skills>'].join('\n')
+}
+
+/**
+ * Renders discoverable skills as a compact markdown list for tool descriptions.
+ * Always includes the heading; renders an explicit no-skills message when empty.
+ */
+export function renderCatalogCompact(options: CatalogOptions): string {
+  const entries = buildCatalogEntries(options)
+
+  const heading = '## Available Systematic Skills'
+
+  if (entries.length === 0) {
+    return `${heading}\n\nNo Systematic skills are currently available.`
+  }
+
+  const bullets = entries
+    .map((entry) => `- ${entry.prefixedName}: ${entry.description}`)
+    .join('\n')
+
+  return `${heading}\n\n${bullets}`
+}

src/lib/skill-catalog.ts

@@ -3,6 +3,11 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { ToolDefinition } from '@opencode-ai/plugin'
 import { tool } from '@opencode-ai/plugin/tool'
+import {
+  buildCatalogEntries,
+  escapeXml,
+  renderCatalogCompact,
+} from './skill-catalog.js'
 import {
   extractSkillBody,
   formatSkillCommandName,
@@ -27,8 +32,8 @@ export function formatSkillsXml(skills: SkillInfo[]): string {
   // Uses space-delimited join with indented XML structure
   const skillLines = skills.flatMap((skill) => [
     '  <skill>',
-    `    <name>${formatSkillCommandName(skill.name)}</name>`,
-    `    <description>${skill.description}</description>`,
+    `    <name>${escapeXml(formatSkillCommandName(skill.name))}</name>`,
+    `    <description>${escapeXml(skill.description)}</description>`,
     `    <location>${pathToFileURL(skill.path).href}</location>`,
     '  </skill>',
   ])
@@ -96,44 +101,23 @@ export function createSkillTool(options: SkillToolOptions): ToolDefinition {
       .sort((a, b) => a.name.localeCompare(b.name))
   }
 
-  const getDiscoverableSkills = (): LoadedSkill[] => {
-    return getAllSkills().filter((s) => s.disableModelInvocation !== true)
-  }
-
   const buildDescription = (): string => {
-    const skills = getDiscoverableSkills()
+    const catalog = renderCatalogCompact({ bundledSkillsDir, disabledSkills })
 
-    if (skills.length === 0) {
-      return 'Load a skill to get detailed instructions for a specific task. No skills are currently available.'
-    }
+    return `Load a specialized skill that provides domain-specific instructions and workflows.
 
-    const skillInfos = skills.map((s) => ({
-      name: s.name,
-      description: s.description,
-      path: s.path,
-      skillFile: s.skillFile,
-    }))
-    const systematicXml = formatSkillsXml(skillInfos)
-
-    return [
-      'Load a specialized skill that provides domain-specific instructions and workflows.',
-      '',
-      'When you recognize that a task matches one of the available skills listed below, use this tool to load the full skill instructions.',
-      '',
-      'The skill will inject detailed instructions, workflows, and access to bundled resources (scripts, references, templates) into the conversation context.',
-      '',
-      'Tool output includes a `<skill_content name="...">` block with the loaded content.',
-      '',
-      'The following skills provide specialized sets of instructions for particular tasks.',
-      'Invoke this tool to load a skill when a task matches one of the available skills listed below:',
-      '',
-      systematicXml,
-    ].join('\n')
+When you recognize that a task matches one of the available skills listed below, use this tool to load the full skill instructions.
+
+The skill will inject detailed instructions, workflows, and access to bundled resources (scripts, references, templates) into the conversation context.
+
+Tool output includes a \`<skill_content name="...">\` block with the loaded content.
+
+${catalog}`
   }
 
   const buildParameterHint = (): string => {
-    const skills = getDiscoverableSkills()
-    const examples = skills
+    const entries = buildCatalogEntries({ bundledSkillsDir, disabledSkills })
+    const examples = entries
       .slice(0, 3)
       .map((s) => `'${s.prefixedName}'`)
       .join(', ')
@@ -172,9 +156,10 @@ export function createSkillTool(options: SkillToolOptions): ToolDefinition {
       const matchedSkill = skills.find((s) => s.name === normalizedName)
 
       if (!matchedSkill) {
-        const availableSystematic = getDiscoverableSkills().map(
-          (s) => s.prefixedName,
-        )
+        const availableSystematic = buildCatalogEntries({
+          bundledSkillsDir,
+          disabledSkills,
+        }).map((s) => s.prefixedName)
         throw new Error(
           `Skill "${requestedName}" not found. Available systematic skills: ${availableSystematic.join(', ')}`,
         )