bash-tool 1.3.5 → 1.3.7

package/README.md

@@ -167,14 +167,80 @@ const customSandbox: Sandbox = {
     // Your implementation here
     return "";
   },
-  async writeFile(path, content) {
-    // Your implementation here
+  async writeFiles(files) {
+    // Your implementation here - files is Array<{path, content}>
   },
 };
 
 const { tools } = await createBashTool({ sandbox: customSandbox });
 ```
 
+## Skills (Experimental)
+
+Skills are modular capabilities that extend agent functionality. Each skill is a directory containing a `SKILL.md` file with instructions and optional scripts.
+
+```typescript
+import {
+  experimental_createSkillTool as createSkillTool,
+  createBashTool,
+} from "bash-tool";
+import { ToolLoopAgent } from "ai";
+
+// Discover skills and get files to upload
+const { loadSkill, files, instructions } = await createSkillTool({
+  skillsDirectory: "./skills",
+});
+
+// Create bash tool with skill files
+const { tools } = await createBashTool({
+  files,
+  extraInstructions: instructions,
+});
+
+// Use both tools with an agent
+const agent = new ToolLoopAgent({
+  model,
+  tools: { loadSkill, ...tools },
+});
+```
+
+### Skill Directory Structure
+
+```
+skills/
+├── csv/
+│   ├── SKILL.md      # Required: instructions with YAML frontmatter
+│   ├── analyze.sh    # Optional: scripts the agent can run
+│   └── filter.sh
+└── text/
+    ├── SKILL.md
+    └── search.sh
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: csv
+description: Analyze and transform CSV files
+---
+
+# CSV Processing
+
+Use `./skills/csv/analyze.sh <file>` to analyze a CSV file.
+```
+
+### How It Works
+
+1. `createSkillTool` discovers skills and returns:
+   - `loadSkill` - Tool for the agent to load a skill's instructions on demand
+   - `files` - All skill files to pass to `createBashTool`
+   - `instructions` - Extra instructions listing available skills
+
+2. The agent sees skill names in the `loadSkill` tool description
+3. When the agent needs a skill, it calls `loadSkill("csv")` to get detailed instructions
+4. The agent uses `bash` to run scripts from `./skills/csv/`
+
 ## AI Agent Instructions
 
 For AI agents working with bash-tool, additional guidance is available in `AGENTS.md`:

package/dist/AGENTS.md

@@ -38,7 +38,7 @@ const result = await agent.generate({
 ## Key Behaviors
 
 1. **Default sandbox is just-bash** - Install `just-bash` or provide your own sandbox
-2. **Working directory defaults to `./workspace`** - All files written relative to `destination`
+2. **Working directory defaults to `/workspace`** - All files written relative to `destination`
 3. **Files are written before tools are returned** - Sandbox is pre-populated
 4. **Tool descriptions include file list** - LLM sees available files in bash tool description
 5. **No `stop()` method** - Sandbox lifecycle is managed externally
@@ -83,11 +83,11 @@ const { tools } = await createBashTool({ sandbox: existingSandbox });
 const { tools } = await createBashTool({
   onBeforeBashCall: ({ command }) => {
     console.log("Running:", command);
-    // Return modified command or undefined to proceed unchanged
+    return undefined; // Or return { command: modifiedCommand } to change it
   },
   onAfterBashCall: ({ command, result }) => {
     console.log(`Exit: ${result.exitCode}`);
-    // Return modified result or undefined to proceed unchanged
+    return undefined; // Or return { result: modifiedResult } to change it
   },
 });
 ```

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export type { JustBashLike } from "./sandbox/just-bash.js";
+export { experimental_createSkillTool } from "./skill-tool.js";
+export type { CreateSkillToolOptions, DiscoveredSkill, Skill, SkillMetadata, SkillToolkit, } from "./skills/types.js";
 export { createBashTool } from "./tool.js";
 export { DEFAULT_MAX_OUTPUT_LENGTH } from "./tools/bash.js";
 export type { BashToolCategory, BashToolInfo, FileFormat, ToolPromptOptions, } from "./tools-prompt.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,OAAO,EACP,qBAAqB,GACtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,KAAK,EACL,aAAa,EACb,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,OAAO,EACP,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { experimental_createSkillTool } from "./skill-tool.js";
 export { createBashTool } from "./tool.js";
 export { DEFAULT_MAX_OUTPUT_LENGTH } from "./tools/bash.js";
 export { bashTools, createToolPrompt, detectFormat, discoverAvailableTools, getToolsByCategory, getToolsForFormat, toolsByFormat, } from "./tools-prompt.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAO5D,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAQ/D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAO5D,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,mBAAmB,CAAC"}

package/dist/skill-tool.d.ts

@@ -0,0 +1,36 @@
+import type { CreateSkillToolOptions, SkillToolkit } from "./skills/types.js";
+/**
+ * Creates a skill toolkit for AI agents.
+ *
+ * Skills are modular capabilities that extend agent functionality.
+ * Each skill is a directory containing a SKILL.md file with instructions
+ * and optional scripts/resources.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   experimental_createSkillTool as createSkillTool,
+ *   createBashTool,
+ * } from "bash-tool";
+ *
+ * // Discover skills and get files
+ * const { loadSkill, skills, files, instructions } = await createSkillTool({
+ *   skillsDirectory: "./skills",
+ * });
+ *
+ * // Create bash tool with skill files
+ * const { tools, sandbox } = await createBashTool({
+ *   files,
+ *   extraInstructions: instructions,
+ * });
+ *
+ * // Use with AI SDK
+ * const result = await generateText({
+ *   model,
+ *   tools: { loadSkill, ...tools },
+ *   prompt: "Process this data using the csv skill",
+ * });
+ * ```
+ */
+export declare function experimental_createSkillTool(options: CreateSkillToolOptions): Promise<SkillToolkit>;
+//# sourceMappingURL=skill-tool.d.ts.map

package/dist/skill-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-tool.d.ts","sourceRoot":"","sources":["../src/skill-tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,sBAAsB,EAEtB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,YAAY,CAAC,CAmDvB"}

package/dist/skill-tool.js

@@ -0,0 +1,103 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { discoverSkills, listSkillFiles } from "./skills/parser.js";
+import { createLoadSkillTool } from "./tools/load-skill.js";
+const DEFAULT_DESTINATION = "skills";
+/**
+ * Creates a skill toolkit for AI agents.
+ *
+ * Skills are modular capabilities that extend agent functionality.
+ * Each skill is a directory containing a SKILL.md file with instructions
+ * and optional scripts/resources.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   experimental_createSkillTool as createSkillTool,
+ *   createBashTool,
+ * } from "bash-tool";
+ *
+ * // Discover skills and get files
+ * const { loadSkill, skills, files, instructions } = await createSkillTool({
+ *   skillsDirectory: "./skills",
+ * });
+ *
+ * // Create bash tool with skill files
+ * const { tools, sandbox } = await createBashTool({
+ *   files,
+ *   extraInstructions: instructions,
+ * });
+ *
+ * // Use with AI SDK
+ * const result = await generateText({
+ *   model,
+ *   tools: { loadSkill, ...tools },
+ *   prompt: "Process this data using the csv skill",
+ * });
+ * ```
+ */
+export async function experimental_createSkillTool(options) {
+    const { skillsDirectory, destination = DEFAULT_DESTINATION } = options;
+    // Discover all skills and collect their files
+    // sandboxDestination uses explicit relative path (e.g., "./skills") - works with any destination
+    const relativeDestination = `./${destination}`;
+    const discoveredSkills = await discoverSkills({
+        skillsDirectory,
+        sandboxDestination: relativeDestination,
+    });
+    // Enrich skills with file lists and collect all files
+    const skills = [];
+    const allFiles = {};
+    for (const skill of discoveredSkills) {
+        const skillFiles = await listSkillFiles(skill.localPath);
+        // Add to skills with file list
+        skills.push({
+            ...skill,
+            files: skillFiles,
+        });
+        // Read and collect all files for this skill
+        const skillDirName = path.basename(skill.localPath);
+        for (const file of skillFiles) {
+            const localFilePath = path.join(skill.localPath, file);
+            const relativeFilePath = `./${path.posix.join(destination, skillDirName, file)}`;
+            try {
+                const content = await fs.readFile(localFilePath, "utf-8");
+                allFiles[relativeFilePath] = content;
+            }
+            catch {
+                // Skip files that can't be read as text
+            }
+        }
+    }
+    // Create loadSkill tool
+    const loadSkill = createLoadSkillTool({ skills });
+    // Generate instructions for bash tool
+    const instructions = generateSkillInstructions(skills);
+    return {
+        loadSkill,
+        skills,
+        files: allFiles,
+        instructions,
+    };
+}
+/**
+ * Generate bash tool instructions that include skill paths.
+ */
+function generateSkillInstructions(skills) {
+    if (skills.length === 0) {
+        return "";
+    }
+    const lines = [
+        "SKILL DIRECTORIES:",
+        "Skills are available at the following paths:",
+    ];
+    for (const skill of skills) {
+        lines.push(`  ${skill.sandboxPath}/ - ${skill.name}: ${skill.description}`);
+    }
+    lines.push("");
+    lines.push("To use a skill:");
+    lines.push("  1. Call loadSkill to get the skill's instructions");
+    lines.push("  2. Run scripts from the skill directory with bash");
+    return lines.join("\n");
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/skill-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-tool.js","sourceRoot":"","sources":["../src/skill-tool.ts"],"names":[],"mappings":"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"}

package/dist/skills/parser.d.ts

@@ -0,0 +1,33 @@
+import type { DiscoveredSkill, SkillMetadata } from "./types.js";
+/**
+ * Parse YAML frontmatter from SKILL.md content using gray-matter.
+ */
+export declare function parseFrontmatter(content: string): SkillMetadata | null;
+/**
+ * Extract the body (instructions) from SKILL.md content.
+ * This is everything after the frontmatter.
+ */
+export declare function extractBody(content: string): string;
+export interface DiscoverSkillsOptions {
+    /** Local directory containing skill subdirectories */
+    skillsDirectory: string;
+    /** Base path in sandbox where skills will be uploaded */
+    sandboxDestination: string;
+}
+/**
+ * Discover all skills in a directory.
+ * Looks for subdirectories containing SKILL.md files.
+ */
+export declare function discoverSkills(options: DiscoverSkillsOptions): Promise<DiscoveredSkill[]>;
+/**
+ * Read and parse a SKILL.md file, returning both metadata and body.
+ */
+export declare function readSkillMd(skillMdPath: string): Promise<{
+    metadata: SkillMetadata;
+    body: string;
+} | null>;
+/**
+ * List files in a skill directory (for listing available scripts).
+ */
+export declare function listSkillFiles(skillPath: string): Promise<string[]>;
+//# sourceMappingURL=parser.d.ts.map

package/dist/skills/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/skills/parser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAqBtE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,EAAE,CAAC,CA0C5B;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAgB3D;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBzE"}

package/dist/skills/parser.js

@@ -0,0 +1,125 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+/**
+ * Parse YAML frontmatter from SKILL.md content using gray-matter.
+ */
+export function parseFrontmatter(content) {
+    try {
+        const { data } = matter(content);
+        // Validate required fields
+        if (typeof data.name !== "string" ||
+            typeof data.description !== "string" ||
+            !data.name ||
+            !data.description) {
+            return null;
+        }
+        return {
+            name: data.name,
+            description: data.description,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract the body (instructions) from SKILL.md content.
+ * This is everything after the frontmatter.
+ */
+export function extractBody(content) {
+    try {
+        const { content: body } = matter(content);
+        return body.trim();
+    }
+    catch {
+        return content.trim();
+    }
+}
+/**
+ * Discover all skills in a directory.
+ * Looks for subdirectories containing SKILL.md files.
+ */
+export async function discoverSkills(options) {
+    const { skillsDirectory, sandboxDestination } = options;
+    const skills = [];
+    const absoluteDir = path.resolve(skillsDirectory);
+    let entries;
+    try {
+        entries = await fs.readdir(absoluteDir);
+    }
+    catch (error) {
+        throw new Error(`Failed to read skills directory: ${absoluteDir}. ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const entryName of entries) {
+        const skillDir = path.join(absoluteDir, entryName);
+        // Check if it's a directory
+        try {
+            const stat = await fs.stat(skillDir);
+            if (!stat.isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const skillMdPath = path.join(skillDir, "SKILL.md");
+        try {
+            const content = await fs.readFile(skillMdPath, "utf-8");
+            const metadata = parseFrontmatter(content);
+            if (metadata) {
+                skills.push({
+                    ...metadata,
+                    localPath: skillDir,
+                    sandboxPath: `${sandboxDestination}/${entryName}`,
+                });
+            }
+        }
+        catch { }
+    }
+    return skills;
+}
+/**
+ * Read and parse a SKILL.md file, returning both metadata and body.
+ */
+export async function readSkillMd(skillMdPath) {
+    try {
+        const content = await fs.readFile(skillMdPath, "utf-8");
+        const metadata = parseFrontmatter(content);
+        if (!metadata) {
+            return null;
+        }
+        return {
+            metadata,
+            body: extractBody(content),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * List files in a skill directory (for listing available scripts).
+ */
+export async function listSkillFiles(skillPath) {
+    const files = [];
+    async function walkDir(dir, prefix = "") {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walkDir(path.join(dir, entry.name), relativePath);
+            }
+            else {
+                files.push(relativePath);
+            }
+        }
+    }
+    try {
+        await walkDir(skillPath);
+    }
+    catch {
+        // Return empty if directory doesn't exist
+    }
+    return files;
+}
+//# sourceMappingURL=parser.js.map

package/dist/skills/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/skills/parser.ts"],"names":[],"mappings":"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"}

package/dist/skills/types.d.ts

@@ -0,0 +1,57 @@
+import type { createLoadSkillTool } from "../tools/load-skill.js";
+/**
+ * Skill metadata parsed from SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+    /** Unique skill name (lowercase, hyphens allowed) */
+    name: string;
+    /** Description of what the skill does and when to use it */
+    description: string;
+}
+/**
+ * Base skill info from discovery (without file list).
+ */
+export interface DiscoveredSkill extends SkillMetadata {
+    /** Absolute path to the skill directory on disk */
+    localPath: string;
+    /** Path to the skill directory in the sandbox */
+    sandboxPath: string;
+}
+/**
+ * Full skill representation with file list.
+ */
+export interface Skill extends DiscoveredSkill {
+    /** List of files in the skill directory (relative paths) */
+    files: string[];
+}
+/**
+ * Options for creating a skill toolkit.
+ */
+export interface CreateSkillToolOptions {
+    /**
+     * Path to the directory containing skill subdirectories.
+     * Each subdirectory should contain a SKILL.md file.
+     * @example "./skills" or "/path/to/skills"
+     */
+    skillsDirectory: string;
+    /**
+     * Relative path within the workspace where skills will be placed.
+     * @default "skills"
+     * @example "skills" -> files at ./skills/...
+     */
+    destination?: string;
+}
+/**
+ * Return type from createSkillTool.
+ */
+export interface SkillToolkit {
+    /** Tool to load a skill's instructions into context */
+    loadSkill: ReturnType<typeof createLoadSkillTool>;
+    /** Registry of discovered skills */
+    skills: Skill[];
+    /** Files to pass to createBashTool (path -> content) */
+    files: Record<string, string>;
+    /** Extra instructions to pass to createBashTool */
+    instructions: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/skills/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,KAAM,SAAQ,eAAe;IAC5C,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,SAAS,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAClD,oCAAoC;IACpC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;CACtB"}

package/dist/skills/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":""}

package/dist/tools/load-skill.d.ts

@@ -0,0 +1,25 @@
+import type { Skill } from "../skills/types.js";
+export interface CreateLoadSkillToolOptions {
+    /** Registry of discovered skills */
+    skills: Skill[];
+}
+export declare function createLoadSkillTool(options: CreateLoadSkillToolOptions): import("ai").Tool<{
+    skillName: string;
+}, {
+    success: boolean;
+    error: string;
+    skill?: undefined;
+    instructions?: undefined;
+    files?: undefined;
+} | {
+    success: boolean;
+    skill: {
+        name: string;
+        description: string;
+        path: string;
+    };
+    instructions: string;
+    files: string[];
+    error?: undefined;
+}>;
+//# sourceMappingURL=load-skill.d.ts.map

package/dist/tools/load-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-skill.d.ts","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAMhD,MAAM,WAAW,0BAA0B;IACzC,oCAAoC;IACpC,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AA0BD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B;;;;;;;;;;;;;;;;;;GAmDtE"}

package/dist/tools/load-skill.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { extractBody } from "../skills/parser.js";
+const loadSkillSchema = z.object({
+    skillName: z.string().describe("The name of the skill to load"),
+});
+function generateDescription(skills) {
+    const lines = [
+        "Load a skill's instructions to learn how to use it.",
+        "You can load multiple skills - each call returns that skill's instructions.",
+        "",
+        "Available skills:",
+    ];
+    if (skills.length === 0) {
+        lines.push("  (no skills found)");
+    }
+    else {
+        for (const skill of skills) {
+            lines.push(`  - ${skill.name}: ${skill.description}`);
+        }
+    }
+    lines.push("");
+    lines.push("After loading a skill, use the bash tool to run its scripts from the skill's directory.");
+    return lines.join("\n");
+}
+export function createLoadSkillTool(options) {
+    const { skills } = options;
+    // Create a map for quick lookup
+    const skillMap = new Map();
+    for (const skill of skills) {
+        skillMap.set(skill.name, skill);
+    }
+    return tool({
+        description: generateDescription(skills),
+        inputSchema: loadSkillSchema,
+        execute: async ({ skillName }) => {
+            const skill = skillMap.get(skillName);
+            if (!skill) {
+                const availableNames = skills.map((s) => s.name).join(", ");
+                return {
+                    success: false,
+                    error: `Skill "${skillName}" not found. Available skills: ${availableNames || "none"}`,
+                };
+            }
+            // Read the SKILL.md from local filesystem
+            const skillMdPath = path.join(skill.localPath, "SKILL.md");
+            try {
+                const content = await fs.readFile(skillMdPath, "utf-8");
+                const body = extractBody(content);
+                // Get files list (excluding SKILL.md)
+                const files = skill.files.filter((f) => f !== "SKILL.md");
+                return {
+                    success: true,
+                    skill: {
+                        name: skill.name,
+                        description: skill.description,
+                        path: skill.sandboxPath,
+                    },
+                    instructions: body,
+                    files,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Failed to read skill "${skillName}": ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=load-skill.js.map

package/dist/tools/load-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-skill.js","sourceRoot":"","sources":["../../src/tools/load-skill.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -22,7 +22,7 @@ export interface BeforeBashCallInput {
 }
 /**
  * Output from onBeforeBashCall callback.
- * Return undefined or the original input to proceed unchanged.
+ * Return nothing to proceed unchanged.
  */
 export interface BeforeBashCallOutput {
     /** The (potentially modified) command to execute */
@@ -39,7 +39,7 @@ export interface AfterBashCallInput {
 }
 /**
  * Output from onAfterBashCall callback.
- * Return undefined or the original result to proceed unchanged.
+ * Return nothing to proceed unchanged.
  */
 export interface AfterBashCallOutput {
     /** The (potentially modified) result */

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "Generic bash tool for AI agents, compatible with AI SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -44,14 +44,15 @@
   },
   "dependencies": {
     "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
     "@types/node": "^22.10.0",
-    "@vercel/sandbox": "^1.1.6",
+    "@vercel/sandbox": "^1.2.0",
     "ai": "^6.0.13",
-    "just-bash": "^2.5.0",
+    "just-bash": "^2.5.1",
     "knip": "^5.80.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.0"
@@ -69,10 +70,9 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
   "scripts": {
     "build": "tsc -p tsconfig.build.json && sed '1,/^-->/d' AGENTS.npm.md > dist/AGENTS.md",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.examples.json",
     "test": "vitest --exclude 'src/tool.vercel.integration.test.ts'",
     "test:run": "vitest run --exclude 'src/tool.vercel.integration.test.ts'",
     "test:vercel": "vitest run src/tool.vercel.integration.test.ts --sequence.concurrent",
@@ -80,6 +80,6 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "knip": "knip",
-    "validate": "pnpm run lint && pnpm run knip && pnpm run typecheck && pnpm run test:run"
+    "validate": "pnpm run lint && pnpm run knip && pnpm run typecheck && pnpm run build && pnpm run test:run"
   }
 }