@probelabs/probe 0.6.0-rc201 → 0.6.0-rc202

package/README.md

@@ -140,6 +140,36 @@ export MODEL_NAME=claude-3-5-sonnet-20241022
 - **Token tracking** - Monitor usage and costs
 - **Configurable personas** - Engineer, architect, code-review, and more
 
+### Agent Skills (repo-local)
+
+ProbeAgent can discover and activate Agent Skills stored inside your repository. Place skills under:
+- `.claude/skills/<skill-name>/SKILL.md`
+- `.codex/skills/<skill-name>/SKILL.md`
+- `skills/<skill-name>/SKILL.md`
+- `.skills/<skill-name>/SKILL.md`
+
+`SKILL.md` should contain YAML frontmatter followed by Markdown instructions. Example:
+
+```markdown
+---
+name: onboarding
+description: Help new engineers understand the repo structure and conventions.
+---
+
+Use this skill to explain key modules, build steps, and common workflows.
+```
+
+Then in the agent loop you can call:
+```xml
+<listSkills></listSkills>
+```
+or:
+```xml
+<useSkill>
+<name>onboarding</name>
+</useSkill>
+```
+
 ### Retry and Fallback Support
 
 ProbeAgent includes comprehensive retry and fallback capabilities for maximum reliability:
@@ -821,4 +851,4 @@ probe mcp --timeout 60
 
 ## Related Projects
 
-- [probe](https://github.com/probelabs/probe) - The core probe code search tool
+- [probe](https://github.com/probelabs/probe) - The core probe code search tool

package/build/agent/ProbeAgent.d.ts

@@ -14,11 +14,13 @@ export interface ProbeAgentOptions {
   /** Alias for customPrompt. More intuitive naming for system prompts. */
   systemPrompt?: string;
   /** Predefined prompt type (persona) */
-  promptType?: 'code-explorer' | 'engineer' | 'code-review' | 'support' | 'architect';
+  promptType?: 'code-explorer' | 'code-searcher' | 'engineer' | 'code-review' | 'support' | 'architect';
   /** Allow the use of the 'implement' tool for code editing */
   allowEdit?: boolean;
   /** Enable the delegate tool for task distribution to subagents */
   enableDelegate?: boolean;
+  /** Architecture context filename to embed from repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present) */
+  architectureFileName?: string;
   /** Enable bash tool for command execution */
   enableBash?: boolean;
   /** Bash tool configuration (allow/deny patterns) */
@@ -36,6 +38,8 @@ export interface ProbeAgentOptions {
   };
   /** Search directory path */
   path?: string;
+  /** Use a delegated code-search subagent for the search tool (default: true) */
+  searchDelegate?: boolean;
   /** Force specific AI provider */
   provider?: 'anthropic' | 'openai' | 'google' | 'bedrock';
   /** Override model name */
@@ -64,6 +68,12 @@ export interface ProbeAgentOptions {
   disableMermaidValidation?: boolean;
   /** Disable automatic JSON validation and fixing (prevents infinite recursion in JsonFixingAgent) */
   disableJsonValidation?: boolean;
+  /** Enable agent skills discovery and activation */
+  enableSkills?: boolean;
+  /** Disable agent skills (overrides enableSkills) */
+  disableSkills?: boolean;
+  /** Skill directories to scan relative to repo root */
+  skillDirs?: string[];
   /** Custom prompt to run after attempt_completion for validation/review (runs before mermaid/JSON validation) */
   completionPrompt?: string;
 }

package/build/agent/ProbeAgent.js

@@ -12,7 +12,7 @@ import { streamText } from 'ai';
 import { randomUUID } from 'crypto';
 import { EventEmitter } from 'events';
 import { existsSync } from 'fs';
-import { readFile, stat } from 'fs/promises';
+import { readFile, stat, readdir } from 'fs/promises';
 import { resolve, isAbsolute, dirname, basename, normalize, sep } from 'path';
 import { TokenCounter } from './tokenCounter.js';
 import { InMemoryStorageAdapter } from './storage/InMemoryStorageAdapter.js';
@@ -27,6 +27,8 @@ import {
   bashToolDefinition,
   listFilesToolDefinition,
   searchFilesToolDefinition,
+  listSkillsToolDefinition,
+  useSkillToolDefinition,
   readImageToolDefinition,
   attemptCompletionToolDefinition,
   implementToolDefinition,
@@ -61,6 +63,9 @@ import {
   parseHybridXmlToolCall,
   loadMCPConfigurationFromPath
 } from './mcp/index.js';
+import { SkillRegistry } from './skills/registry.js';
+import { formatAvailableSkillsXml } from './skills/formatting.js';
+import { createSkillToolInstances } from './skills/tools.js';
 import { RetryManager, createRetryManagerFromEnv } from './RetryManager.js';
 import { FallbackManager, createFallbackManagerFromEnv, buildFallbackProvidersFromEnv } from './FallbackManager.js';
 import { handleContextLimitError } from './contextCompactor.js';
@@ -91,19 +96,24 @@ export class ProbeAgent {
    * @param {string} [options.sessionId] - Optional session ID
    * @param {string} [options.customPrompt] - Custom prompt to replace the default system message
    * @param {string} [options.systemPrompt] - Alias for customPrompt; takes precedence when both are provided
-   * @param {string} [options.promptType] - Predefined prompt type (architect, code-review, support)
+   * @param {string} [options.promptType] - Predefined prompt type (code-explorer, code-searcher, architect, code-review, support)
    * @param {boolean} [options.allowEdit=false] - Allow the use of the 'implement' tool
    * @param {boolean} [options.enableDelegate=false] - Enable the delegate tool for task distribution to subagents
+   * @param {string} [options.architectureFileName] - Architecture context filename to embed from repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present)
    * @param {string} [options.path] - Search directory path
    * @param {string} [options.cwd] - Working directory for resolving relative paths (independent of allowedFolders)
    * @param {string} [options.provider] - Force specific AI provider
    * @param {string} [options.model] - Override model name
    * @param {boolean} [options.debug] - Enable debug mode
    * @param {boolean} [options.outline] - Enable outline-xml format for search results
+   * @param {boolean} [options.searchDelegate=true] - Use a delegated code-search subagent for the search tool
    * @param {number} [options.maxResponseTokens] - Maximum tokens for AI responses
    * @param {number} [options.maxIterations] - Maximum tool iterations (overrides MAX_TOOL_ITERATIONS env var)
    * @param {boolean} [options.disableMermaidValidation=false] - Disable automatic mermaid diagram validation and fixing
    * @param {boolean} [options.disableJsonValidation=false] - Disable automatic JSON validation and fixing (prevents infinite recursion in JsonFixingAgent)
+   * @param {boolean} [options.enableSkills=true] - Enable agent skills discovery and activation
+   * @param {boolean} [options.disableSkills=false] - Disable agent skills (overrides enableSkills)
+   * @param {Array<string>} [options.skillDirs] - Skill directories to scan relative to repo root
    * @param {boolean} [options.enableMcp=false] - Enable MCP tool integration
    * @param {string} [options.mcpConfigPath] - Path to MCP configuration file
    * @param {Object} [options.mcpConfig] - MCP configuration object (overrides mcpConfigPath)
@@ -138,6 +148,7 @@ export class ProbeAgent {
     this.cancelled = false;
     this.tracer = options.tracer || null;
     this.outline = !!options.outline;
+    this.searchDelegate = options.searchDelegate !== undefined ? !!options.searchDelegate : true;
     this.maxResponseTokens = options.maxResponseTokens || (() => {
       const val = parseInt(process.env.MAX_RESPONSE_TOKENS || '0', 10);
       if (isNaN(val) || val < 0 || val > 200000) {
@@ -148,6 +159,16 @@ export class ProbeAgent {
     this.maxIterations = options.maxIterations || null;
     this.disableMermaidValidation = !!options.disableMermaidValidation;
     this.disableJsonValidation = !!options.disableJsonValidation;
+    this.enableSkills = options.disableSkills ? false : (options.enableSkills !== undefined ? !!options.enableSkills : true);
+    if (Array.isArray(options.skillDirs)) {
+      this.skillDirs = options.skillDirs;
+    } else if (typeof options.skillDirs === 'string') {
+      this.skillDirs = options.skillDirs.split(',').map(dir => dir.trim()).filter(Boolean);
+    } else {
+      this.skillDirs = null;
+    }
+    this.skillsRegistry = null;
+    this.activeSkills = new Map();
 
     // Completion prompt for post-completion validation/review
     this.completionPrompt = options.completionPrompt || null;
@@ -176,6 +197,15 @@ export class ProbeAgent {
     this.enableBash = !!options.enableBash;
     this.bashConfig = options.bashConfig || {};
 
+    // Architecture context configuration
+    const configuredArchitectureFileName =
+      typeof options.architectureFileName === 'string' && options.architectureFileName.trim()
+        ? options.architectureFileName
+        : null;
+    this.architectureFileName = configuredArchitectureFileName;
+    this.architectureContext = null;
+    this._architectureContextLoaded = false;
+
     // Search configuration - support both path (single) and allowedFolders (array)
     if (options.allowedFolders && Array.isArray(options.allowedFolders)) {
       this.allowedFolders = options.allowedFolders;
@@ -201,6 +231,7 @@ export class ProbeAgent {
       console.log(`[DEBUG] Generated session ID for agent: ${this.sessionId}`);
       console.log(`[DEBUG] Maximum tool iterations configured: ${MAX_TOOL_ITERATIONS}`);
       console.log(`[DEBUG] Allow Edit (implement tool): ${this.allowEdit}`);
+      console.log(`[DEBUG] Search delegation enabled: ${this.searchDelegate}`);
     }
 
     // Initialize tools
@@ -437,11 +468,16 @@ export class ProbeAgent {
       cwd: this.cwd || (this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd()),
       allowedFolders: this.allowedFolders,
       outline: this.outline,
+      searchDelegate: this.searchDelegate,
       allowEdit: this.allowEdit,
       enableDelegate: this.enableDelegate,
       enableBash: this.enableBash,
       bashConfig: this.bashConfig,
+      tracer: this.tracer,
       allowedTools: this.allowedTools,
+      architectureFileName: this.architectureFileName,
+      provider: this.clientApiProvider,
+      model: this.clientApiModel,
       isToolAllowed
     };
 
@@ -475,6 +511,21 @@ export class ProbeAgent {
       this.toolImplementations.searchFiles = searchFilesToolInstance;
     }
 
+    if (this.enableSkills) {
+      const registry = this._getSkillsRegistry();
+      const { listSkillsToolInstance, useSkillToolInstance } = createSkillToolInstances({
+        registry,
+        activeSkills: this.activeSkills
+      });
+
+      if (isToolAllowed('listSkills')) {
+        this.toolImplementations.listSkills = listSkillsToolInstance;
+      }
+      if (isToolAllowed('useSkill')) {
+        this.toolImplementations.useSkill = useSkillToolInstance;
+      }
+    }
+
     // Image loading tool
     if (isToolAllowed('readImage')) {
       this.toolImplementations.readImage = {
@@ -1043,7 +1094,7 @@ export class ProbeAgent {
 
         // For Claude Code, use a cleaner system prompt without XML formatting
         // since it has native MCP support for tools
-        const systemPrompt = this.customPrompt || this.getClaudeNativeSystemPrompt();
+        const systemPrompt = await this.getClaudeNativeSystemPrompt();
 
         this.engine = await createEnhancedClaudeCLIEngine({
           agent: this, // Pass reference to ProbeAgent for tool access
@@ -1074,7 +1125,7 @@ export class ProbeAgent {
 
         // For Codex CLI, use a cleaner system prompt without XML formatting
         // since it has native MCP support for tools
-        const systemPrompt = this.customPrompt || this.getCodexNativeSystemPrompt();
+        const systemPrompt = await this.getCodexNativeSystemPrompt();
 
         this.engine = await createCodexEngine({
           agent: this, // Pass reference to ProbeAgent for tool access
@@ -1535,11 +1586,207 @@ export class ProbeAgent {
     }
   }
 
+  /**
+   * Load architecture context from repository root (case-insensitive filename match)
+   * @returns {Promise<Object|null>} Architecture context with { name, path, content, sources, primarySource, guidanceSource, architectureSource } or null
+   */
+  async loadArchitectureContext() {
+    if (this._architectureContextLoaded) {
+      return this.architectureContext;
+    }
+
+    const rootDirectory = this.allowedFolders.length > 0 ? this.allowedFolders[0] : process.cwd();
+    const configuredName =
+      typeof this.architectureFileName === 'string' ? this.architectureFileName.trim() : '';
+    const hasConfiguredName = !!configuredName;
+    let guidanceCandidates = [];
+
+    if (hasConfiguredName) {
+      const targetName = basename(configuredName);
+
+      // Only allow simple filenames (no path separators or traversal)
+      if (
+        configuredName !== targetName ||
+        configuredName.includes('/') ||
+        configuredName.includes('\\') ||
+        configuredName.includes('..') ||
+        isAbsolute(configuredName)
+      ) {
+        console.warn(`[WARN] Invalid architectureFileName (must be a simple filename): ${configuredName}`);
+      } else if (targetName) {
+        const targetLower = targetName.toLowerCase();
+        if (targetLower === 'agents.md') {
+          guidanceCandidates = ['agents.md', 'claude.md'];
+        } else {
+          guidanceCandidates = [targetName];
+        }
+      }
+    } else {
+      guidanceCandidates = ['agents.md', 'claude.md'];
+    }
+
+    if (!existsSync(rootDirectory)) {
+      this._architectureContextLoaded = true;
+      return null;
+    }
+
+    let entries;
+    try {
+      entries = await readdir(rootDirectory, { withFileTypes: true });
+    } catch (error) {
+      this.architectureContext = null;
+      if (error && (error.code === 'EACCES' || error.code === 'EPERM')) {
+        console.warn(`[WARN] Cannot read architecture context directory: ${rootDirectory} (${error.code})`);
+      } else if (this.debug) {
+        console.log(`[DEBUG] Could not list architecture context directory: ${error.message}`);
+      }
+      return null;
+    }
+
+    const entryByLower = new Map();
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      entryByLower.set(entry.name.toLowerCase(), entry);
+    }
+
+    let guidanceMatch = null;
+    for (const candidateName of guidanceCandidates) {
+      const entry = entryByLower.get(candidateName.toLowerCase());
+      if (entry) {
+        guidanceMatch = entry;
+        break;
+      }
+    }
+
+    const architectureMatch = entryByLower.get('architecture.md');
+    const guidanceKey = guidanceMatch ? guidanceMatch.name.toLowerCase() : null;
+    const architectureKey = architectureMatch ? architectureMatch.name.toLowerCase() : null;
+
+    if (!guidanceMatch && !architectureMatch) {
+      this._architectureContextLoaded = true;
+      return null;
+    }
+
+    const uniqueEntries = [];
+    const seen = new Set();
+    const pushEntry = (entry) => {
+      if (!entry) return;
+      const key = entry.name.toLowerCase();
+      if (seen.has(key)) return;
+      seen.add(key);
+      uniqueEntries.push(entry);
+    };
+
+    pushEntry(guidanceMatch);
+    pushEntry(architectureMatch);
+
+    const contexts = [];
+    for (const entry of uniqueEntries) {
+      const filePath = resolve(rootDirectory, entry.name);
+      try {
+        const content = await readFile(filePath, 'utf8');
+        let kind = 'other';
+        const entryKey = entry.name.toLowerCase();
+        if (guidanceKey && entryKey === guidanceKey) {
+          kind = 'guidance';
+        } else if (architectureKey && entryKey === architectureKey) {
+          kind = 'architecture';
+        }
+        contexts.push({
+          name: entry.name,
+          path: filePath,
+          content,
+          kind
+        });
+      } catch (error) {
+        if (error && (error.code === 'EACCES' || error.code === 'EPERM')) {
+          console.warn(`[WARN] Cannot read architecture context file: ${filePath} (${error.code})`);
+        } else if (error && error.code === 'ENOENT') {
+          if (this.debug) {
+            console.log(`[DEBUG] Architecture context file disappeared: ${filePath}`);
+          }
+        } else {
+          console.warn(`[WARN] Failed to read architecture context file: ${filePath} (${error.message})`);
+        }
+      }
+    }
+
+    if (!contexts.length) {
+      this.architectureContext = null;
+      this._architectureContextLoaded = true;
+      return null;
+    }
+
+    const guidanceSource = contexts.find((context) => context.kind === 'guidance') || null;
+    const architectureSource = contexts.find((context) => context.kind === 'architecture') || null;
+    const primarySource = guidanceSource || architectureSource || contexts[0];
+
+    this.architectureContext = {
+      name: primarySource?.name || null,
+      path: primarySource?.path || null,
+      content: contexts.map((context) => context.content).join('\n\n'),
+      sources: contexts,
+      primarySource,
+      guidanceSource,
+      architectureSource
+    };
+    this._architectureContextLoaded = true;
+
+    return this.architectureContext;
+  }
+
+  /**
+   * Format architecture context for prompt inclusion
+   * @returns {string} Architecture section or empty string
+   */
+  getArchitectureSection() {
+    if (!this.architectureContext?.content) {
+      return '';
+    }
+
+    return `\n\n# Architecture\n\n${this.architectureContext.content}\n`;
+  }
+
+  _getSkillsRepoRoot() {
+    if (this.allowedFolders && this.allowedFolders.length > 0) {
+      return resolve(this.allowedFolders[0]);
+    }
+    return process.cwd();
+  }
+
+  _getSkillsRegistry() {
+    if (!this.skillsRegistry) {
+      this.skillsRegistry = new SkillRegistry({
+        repoRoot: this._getSkillsRepoRoot(),
+        skillDirs: this.skillDirs || undefined,
+        debug: this.debug
+      });
+    }
+    return this.skillsRegistry;
+  }
+
+  async _loadSkillsMetadata() {
+    if (!this.enableSkills) return [];
+    return await this._getSkillsRegistry().loadSkills();
+  }
+
+  async _getAvailableSkillsXml() {
+    const skills = await this._loadSkillsMetadata();
+    if (!skills.length) return '';
+    return formatAvailableSkillsXml(skills);
+  }
+
   /**
    * Get system prompt for Claude native engines (CLI/SDK) without XML formatting
    * These engines have native MCP support and don't need XML instructions
    */
-  getClaudeNativeSystemPrompt() {
+  async getClaudeNativeSystemPrompt() {
+    await this.loadArchitectureContext();
     let systemPrompt = '';
 
     // Add persona/role if configured
@@ -1564,10 +1811,17 @@ export class ProbeAgent {
       systemPrompt += `\n- bash: Execute bash commands for system operations`;
     }
 
+    const searchGuidance = this.searchDelegate
+      ? '1. Start with search to retrieve extracted code blocks'
+      : '1. Start with search to find relevant code patterns';
+    const extractGuidance = this.searchDelegate
+      ? '2. Use extract only if you need more context or a full file'
+      : '2. Use extract to get detailed context when needed';
+
     systemPrompt += `\n
 When exploring code:
-1. Start with search to find relevant code patterns
-2. Use extract to get detailed context when needed
+${searchGuidance}
+${extractGuidance}
 3. Prefer focused, specific searches over broad queries
 4. Combine multiple tools to build complete understanding`;
 
@@ -1584,13 +1838,17 @@ When exploring code:
       systemPrompt += '```\n' + this.fileList + '\n```\n';
     }
 
+    // Add architecture context if available
+    systemPrompt += this.getArchitectureSection();
+
     return systemPrompt;
   }
 
   /**
    * Get system prompt for Codex CLI (similar to Claude but optimized for Codex)
    */
-  getCodexNativeSystemPrompt() {
+  async getCodexNativeSystemPrompt() {
+    await this.loadArchitectureContext();
     let systemPrompt = '';
 
     // Add persona/role if configured
@@ -1615,10 +1873,17 @@ When exploring code:
       systemPrompt += `\n- bash: Execute bash commands for system operations`;
     }
 
+    const searchGuidance = this.searchDelegate
+      ? '1. Start with search to retrieve extracted code blocks'
+      : '1. Start with search to find relevant code patterns';
+    const extractGuidance = this.searchDelegate
+      ? '2. Use extract only if you need more context or a full file'
+      : '2. Use extract to get detailed context when needed';
+
     systemPrompt += `\n
 When exploring code:
-1. Start with search to find relevant code patterns
-2. Use extract to get detailed context when needed
+${searchGuidance}
+${extractGuidance}
 3. Prefer focused, specific searches over broad queries
 4. Combine multiple tools to build complete understanding`;
 
@@ -1635,6 +1900,9 @@ When exploring code:
       systemPrompt += '```\n' + this.fileList + '\n```\n';
     }
 
+    // Add architecture context if available
+    systemPrompt += this.getArchitectureSection();
+
     return systemPrompt;
   }
 
@@ -1676,7 +1944,10 @@ When exploring code:
 
     // Core tools (filtered by allowedTools)
     if (isToolAllowed('search')) {
-      toolDefinitions += `${searchToolDefinition}\n`;
+      const searchDefinition = this.searchDelegate
+        ? `${searchToolDefinition}\n**Note:** This search tool delegates code searching to a dedicated subagent and returns extracted code blocks. Use extract only to expand context or if search returns no code.`
+        : searchToolDefinition;
+      toolDefinitions += `${searchDefinition}\n`;
     }
     if (isToolAllowed('query')) {
       toolDefinitions += `${queryToolDefinition}\n`;
@@ -1690,6 +1961,12 @@ When exploring code:
     if (isToolAllowed('searchFiles')) {
       toolDefinitions += `${searchFilesToolDefinition}\n`;
     }
+    if (this.enableSkills && isToolAllowed('listSkills')) {
+      toolDefinitions += `${listSkillsToolDefinition}\n`;
+    }
+    if (this.enableSkills && isToolAllowed('useSkill')) {
+      toolDefinitions += `${useSkillToolDefinition}\n`;
+    }
     if (isToolAllowed('readImage')) {
       toolDefinitions += `${readImageToolDefinition}\n`;
     }
@@ -1778,12 +2055,12 @@ I need to find code related to error handling in the search module. The most app
 10. If your previous response was already correct and complete, you may use \`<attempt_complete>\` as a shorthand.
 
 Available Tools:
-- search: Search code using keyword queries.
+- search: Search code using keyword queries${this.searchDelegate ? ' (returns extracted code blocks via a dedicated subagent)' : ''}.
 - query: Search code using structural AST patterns.
 - extract: Extract specific code blocks or lines from files.
 - listFiles: List files and directories in a specified location.
 - searchFiles: Find files matching a glob pattern with recursive search capability.
-- readImage: Read and load an image file for AI analysis.
+${this.enableSkills ? '- listSkills: List available agent skills discovered in the repository.\n- useSkill: Load and activate a specific skill\'s instructions.\n' : ''}- readImage: Read and load an image file for AI analysis.
 ${this.allowEdit ? '- implement: Implement a feature or fix a bug using aider.\n- edit: Edit files using exact string replacement.\n- create: Create new files with specified content.\n' : ''}${this.enableDelegate ? '- delegate: Delegate big distinct tasks to specialized probe subagents.\n' : ''}${this.enableBash ? '- bash: Execute bash commands for system operations.\n' : ''}
 - attempt_completion: Finalize the task and provide the result to the user.
 - attempt_complete: Quick completion using previous response (shorthand).
@@ -1795,7 +2072,7 @@ Follow these instructions carefully:
 1. Analyze the user's request.
 2. Use <thinking></thinking> tags to analyze the situation and determine the appropriate tool for each step.
 3. Use the available tools step-by-step to fulfill the request.
-4. You should always prefer the \`search\` tool for code-related questions. Read full files only if really necessary.
+4. You should always prefer the \`search\` tool for code-related questions.${this.searchDelegate ? ' It already returns extracted code blocks; use \`extract\` only to expand context or read full files.' : ' Read full files only if really necessary.'}
 5. Ensure to get really deep and understand the full picture before answering.
 6. You MUST respond with exactly ONE tool call per message, using the specified XML format, until the task is complete.
 7. Wait for the tool execution result (provided in the next user message in a <tool_result> block) before proceeding to the next step.
@@ -1841,6 +2118,14 @@ Follow these instructions carefully:
     // Add Tool Definitions
     systemMessage += `\n# Tools Available\n${toolDefinitions}\n`;
 
+    // Add available skills (metadata only)
+    if (this.enableSkills) {
+      const skillsXml = await this._getAvailableSkillsXml();
+      if (skillsXml) {
+        systemMessage += `\n# Available Skills\n${skillsXml}\n\nTo use a skill, call the useSkill tool with its name.\n`;
+      }
+    }
+
     // Add MCP tools if available (filtered by allowedTools)
     if (this.mcpBridge && this.mcpBridge.getToolNames().length > 0) {
       const allMcpTools = this.mcpBridge.getToolNames();
@@ -1876,6 +2161,10 @@ Follow these instructions carefully:
       systemMessage += `\n# Repository Structure\n\nYou are working with a repository located at: ${searchDirectory}\n\n`;
     }
 
+    // Add architecture context if available
+    await this.loadArchitectureContext();
+    systemMessage += this.getArchitectureSection();
+
     if (this.allowedFolders.length > 0) {
       systemMessage += `\n**Important**: For security reasons, you can only search within these allowed folders: ${this.allowedFolders.join(', ')}\n\n`;
     }
@@ -2330,6 +2619,8 @@ Follow these instructions carefully:
           if (this.allowedTools.isEnabled('extract')) validTools.push('extract');
           if (this.allowedTools.isEnabled('listFiles')) validTools.push('listFiles');
           if (this.allowedTools.isEnabled('searchFiles')) validTools.push('searchFiles');
+          if (this.enableSkills && this.allowedTools.isEnabled('listSkills')) validTools.push('listSkills');
+          if (this.enableSkills && this.allowedTools.isEnabled('useSkill')) validTools.push('useSkill');
           if (this.allowedTools.isEnabled('readImage')) validTools.push('readImage');
           // Always allow attempt_completion - it's a completion signal, not a tool
           // This ensures agents can complete even when disableTools: true is set (fixes #333)
@@ -2518,6 +2809,7 @@ Follow these instructions carefully:
                       path: this.searchPath,            // Inherit search path
                       provider: this.apiType,           // Inherit AI provider (string identifier)
                       model: this.model,                // Inherit model
+                      searchDelegate: this.searchDelegate,
                       debug: this.debug,
                       tracer: this.tracer
                     };
@@ -3371,6 +3663,7 @@ Convert your previous response content into actual JSON data that follows this s
       promptType: this.promptType,
       allowEdit: this.allowEdit,
       enableDelegate: this.enableDelegate,
+      architectureFileName: this.architectureFileName,
       path: this.allowedFolders[0], // Use first allowed folder as primary path
       allowedFolders: [...this.allowedFolders],
       cwd: this.cwd, // Preserve explicit working directory
@@ -3378,11 +3671,14 @@ Convert your previous response content into actual JSON data that follows this s
       model: this.clientApiModel,
       debug: this.debug,
       outline: this.outline,
+      searchDelegate: this.searchDelegate,
       maxResponseTokens: this.maxResponseTokens,
       maxIterations: this.maxIterations,
       disableMermaidValidation: this.disableMermaidValidation,
       disableJsonValidation: this.disableJsonValidation,
       completionPrompt: this.completionPrompt,
+      enableSkills: this.enableSkills,
+      skillDirs: this.skillDirs ? [...this.skillDirs] : null,
       allowedTools: allowedToolsArray,
       enableMcp: !!this.mcpBridge,
       mcpConfig: this.mcpConfig,