@gizmo-ai/skill-plugin

Skill discovery and lifecycle plugin for Gizmo runtime. Implements the Agent Skills specification.

Installation

bun add @gizmo-ai/skill-plugin

Usage

import { skillPlugin } from "@gizmo-ai/skill-plugin";
import { agentPlugin } from "@gizmo-ai/agent-plugin";
import { createRuntime } from "@gizmo-ai/runtime";

const runtime = createRuntime({
  plugins: [
    skillPlugin({ cwd: process.cwd() }),
    agentPlugin({
      model: openAI(),
      systemMessage: baseSystemMessage
    })
  ]
});

Skills are automatically appended to the system prompt when the runtime initializes.

Skill Discovery

Skills are discovered from:

• ~/.gizmo/skills/ (user-level skills)
• .gizmo/skills/ (project-level skills)

Skill Format

Skills follow the Agent Skills specification. Create a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: A helpful skill for specific tasks
---

# My Skill

Instructions for the agent...

Or create subdirectories with SKILL.md:

.gizmo/skills/
  my-skill/
    SKILL.md
    templates/
      example.txt

Actions

The plugin emits:

• SKILL_SKILLS_DISCOVERED - At startup with all discovered skills
• SKILL_SKILL_LOADED - When agent reads a skill file
• SKILL_SKILL_CREATED - When agent creates a new skill
• SKILL_SKILL_REMOVED - When a skill directory is deleted (via filesystem watch)

API

skillPlugin(config)

Create the skill plugin.

const skills = skillPlugin({
  cwd: process.cwd(),      // Project directory (default: process.cwd())
  configDir: "~/.gizmo",   // User config directory (default: ~/.gizmo)
  skillPaths: []           // Additional skill paths
});

skills.getDiscoveredSkills()

Get all discovered skills.

skills.isSkillLoaded(name)

Check if a skill has been loaded.

skills.stopWatching()

Stop filesystem watchers (for cleanup).

Standalone Functions

import {
  loadSkills,
  formatSkillsForPrompt,
  findSkillByPath
} from "@gizmo-ai/skill-plugin";

// Load skills from directories
const { skills, diagnostics } = loadSkills({ cwd: "/project" });

// Format for prompt
const promptXml = formatSkillsForPrompt(skills);

// Find skill by file path
const skill = findSkillByPath("/path/to/file.md", skills);