@sisu-ai/mw-skills

v3.0.0

Published

3 months ago

Load reusable filesystem skills (`SKILL.md`) so agents can discover and apply curated workflows.

0High
0Medium
0Low

lejahmie

@sisu-ai/mw-skills

Load reusable filesystem skills (SKILL.md) so agents can discover and apply curated workflows.

Setup

npm i @sisu-ai/mw-skills

What It Does

Discovers skills from explicitly configured directories (no implicit defaults).
Registers a use_skill tool that loads full skill instructions on demand.
Injects skill metadata into the system prompt to enable LLM-native matching.

Usage

import { skillsMiddleware } from "@sisu-ai/mw-skills";

const app = new Agent().use(
  skillsMiddleware({ directories: [".sisu/skills"] }),
);

Tool alias compatibility

Many ecosystem skills expect snake_case tool names like read_file. Use tool aliases to match.

registerTools(terminal.tools, {
  aliases: {
    terminalRun: "bash",
    terminalReadFile: "read_file",
    terminalCd: "cd",
  },
});

Configuration

interface SkillsOptions {
  /** Required: directories to scan for skills */
  directories?: string[];

  /** Optional single-directory shorthand */
  directory?: string;

  /** Base path for resolving relative directories (default: process.cwd()) */
  cwd?: string;

  /** Max file size for resources (bytes, default: 100KB) */
  maxFileSize?: number;

  /** Max total size per skill (bytes, default: 500KB) */
  maxSkillSize?: number;

  /** Cache TTL in ms (default: 5 minutes) */
  cacheTtl?: number;

  /** Include only specific skill names */
  include?: string[];

  /** Exclude specific skill names */
  exclude?: string[];
}

Progressive Disclosure

Skills are loaded in three levels to reduce prompt size:

Metadata (name + description) in the system prompt
Instructions loaded when use_skill is called
Resources loaded on demand (read via tools)

Examples

examples/openai-skills
examples/anthropic-skills

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.