@sisu-ai/mw-skills

Filesystem-based skills middleware for SISU. Skills are SKILL.md files with YAML frontmatter plus optional resources.

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:

1. Metadata (name + description) in the system prompt
2. Instructions loaded when use_skill is called
3. 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.

• Code of Conduct
• Contributing Guide
• License
• Report a Bug
• Request a Feature