sdk: skills dir parameter

Author: jahooma

sdk/src/__tests__/initial-session-state.test.ts

@@ -1,3 +1,7 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import os from 'os'
+import path from 'path'
+
 import { describe, expect, test, beforeEach } from 'bun:test'
 import { z } from 'zod/v4'
 
@@ -310,6 +314,62 @@ describe('Initial Session State', () => {
     expect(sessionState.fileContext.systemInfo.cpus).toBeGreaterThan(0)
   })
 
+  test('loads skills from skillsDir when provided', async () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'sdk-skills-test-'))
+    try {
+      const skillDir = path.join(tmpDir, 'my-skill')
+      mkdirSync(skillDir, { recursive: true })
+      writeFileSync(
+        path.join(skillDir, 'SKILL.md'),
+        [
+          '---',
+          'name: my-skill',
+          'description: A test skill',
+          '---',
+          '',
+          '# My Skill',
+          '',
+          'Some instructions here.',
+        ].join('\n'),
+      )
+
+      const sessionState = await initialSessionState({
+        cwd: '/test-project',
+        skillsDir: tmpDir,
+        projectFiles: { 'src/index.ts': 'console.log("hello");' },
+        fs: mockFs,
+        logger: mockLogger,
+      })
+
+      expect(sessionState.fileContext.skills).toBeDefined()
+      expect(sessionState.fileContext.skills!['my-skill']).toBeDefined()
+      expect(sessionState.fileContext.skills!['my-skill'].name).toBe('my-skill')
+      expect(sessionState.fileContext.skills!['my-skill'].description).toBe(
+        'A test skill',
+      )
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  test('skillsDir with no valid skills results in empty skills map', async () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'sdk-skills-test-'))
+    try {
+      const sessionState = await initialSessionState({
+        cwd: '/test-project',
+        skillsDir: tmpDir,
+        projectFiles: { 'src/index.ts': 'console.log("hello");' },
+        fs: mockFs,
+        logger: mockLogger,
+      })
+
+      expect(sessionState.fileContext.skills).toBeDefined()
+      expect(Object.keys(sessionState.fileContext.skills!)).toHaveLength(0)
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
   test('initializes empty agent state correctly', async () => {
     const projectFiles = {
       'src/index.ts': 'console.log("Hello world");',

sdk/src/client.ts

@@ -47,6 +47,7 @@ export class CodebuffClient {
    * @param knowledgeFiles - (Optional) Knowledge files to inject into every run() call. Uses the same schema as projectFiles - keys are file paths and values are file contents. These files are added directly to the agent's context.
    * @param agentDefinitions - (Optional) Array of custom agent definitions. Each object should satisfy the AgentDefinition type. You can input the agent's id field into the agent parameter to run that agent.
    * @param customToolDefinitions - (Optional) Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.
+   * @param skillsDir - (Optional) Path to a directory containing skills to load. Each skill should be in its own subdirectory with a SKILL.md file (e.g., `skillsDir/my-skill/SKILL.md`). When provided, skills are loaded from this directory instead of the default locations. The loaded skills will be listed in the `skill` tool's description and can be loaded by the agent.
    * @param maxAgentSteps - (Optional) Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.
    * @param env - (Optional) Environment variables to pass to terminal commands executed by the agent. These will be merged with the current process environment, with the custom values taking precedence. Can also be provided in individual run() calls to override.
    *

sdk/src/index.ts

@@ -10,6 +10,7 @@ export { run } from './run'
 export { getFiles } from './tools/read-files'
 export type { FileFilter, FileFilterResult } from './tools/read-files'
 export type {
+  CodebuffClientOptions,
   RunOptions,
   MessageContent,
   TextContent,

sdk/src/run-state.ts

@@ -67,6 +67,8 @@ export type RunState = {
 
 export type InitialSessionStateOptions = {
   cwd?: string
+  /** Optional directory path to load skills from. When provided, skills are loaded from this directory instead of the default locations. */
+  skillsDir?: string
   projectFiles?: Record<string, string>
   knowledgeFiles?: Record<string, string>
   /** User-provided knowledge files that will be merged with home directory files */
@@ -407,7 +409,7 @@ function deriveKnowledgeFiles(
 export async function initialSessionState(
   params: InitialSessionStateOptions,
 ): Promise<SessionState> {
-  const { cwd, maxAgentSteps } = params
+  const { cwd, maxAgentSteps, skillsDir } = params
   let {
     agentDefinitions,
     customToolDefinitions,
@@ -488,7 +490,7 @@ export async function initialSessionState(
   }
 
   // Load skills from project and home directories
-  const skills = await loadSkills({ cwd: cwd ?? process.cwd(), verbose: false })
+  const skills = await loadSkills({ cwd: cwd ?? process.cwd(), skillsPath: skillsDir, verbose: false })
 
   const initialState = getInitialSessionState({
     projectRoot: cwd ?? process.cwd(),
@@ -523,6 +525,7 @@ export async function initialSessionState(
 
 export async function generateInitialRunState({
   cwd,
+  skillsDir,
   projectFiles,
   knowledgeFiles,
   userKnowledgeFiles,
@@ -532,6 +535,7 @@ export async function generateInitialRunState({
   fs,
 }: {
   cwd: string
+  skillsDir?: string
   projectFiles?: Record<string, string>
   knowledgeFiles?: Record<string, string>
   userKnowledgeFiles?: Record<string, string>
@@ -543,6 +547,7 @@ export async function generateInitialRunState({
   return {
     sessionState: await initialSessionState({
       cwd,
+      skillsDir,
       projectFiles,
       knowledgeFiles,
       userKnowledgeFiles,

sdk/src/run.ts

@@ -71,6 +71,8 @@ export type CodebuffClientOptions = {
   apiKey?: string
 
   cwd?: string
+  /** Optional directory path to load skills from. Skills found here will be available to the `skill` tool. */
+  skillsDir?: string
   projectFiles?: Record<string, string>
   knowledgeFiles?: Record<string, string>
   agentDefinitions?: AgentDefinition[]
@@ -180,6 +182,7 @@ async function runOnce({
   fingerprintId,
 
   cwd,
+  skillsDir,
   projectFiles,
   knowledgeFiles,
   agentDefinitions,
@@ -244,6 +247,7 @@ async function runOnce({
     // No previous run, so create a fresh session state
     sessionState = await initialSessionState({
       cwd,
+      skillsDir,
       knowledgeFiles,
       agentDefinitions,
       customToolDefinitions,