Plugin Skill Loader

README

# @elizaos/plugin-skill-loader

Convert OpenClaw SKILL.md files into live ElizaOS plugins. Bridge between ecosystems.

## What It Does

```
SKILL.md → Parser → ParsedSkill → Converter → ElizaOS Plugin
                                                 ├── Actions (natural language triggers)
                                                 ├── Providers (contextual knowledge)
                                                 └── Commands (optional shell execution)
```

| Action | Description |
|--------|-------------|
| `LOAD_SKILL` | Load a SKILL.md file at runtime |
| `LIST_SKILLS` | Show all loaded skills |
| `GENERATE_PLUGIN` | Export a skill as a standalone TypeScript plugin directory |

## SKILL.md Format

OpenClaw skills use a simple format — YAML frontmatter + markdown:

```markdown
---
name: weather
description: "Get weather and forecasts. Use when: user asks about weather."
metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }
---

# Weather Skill

## When to Use
- "What's the weather?"
- "Will it rain tomorrow?"
- Temperature checks

## When NOT to Use
- Historical weather data
- Aviation weather (METAR)

## Commands

### Current Weather
\`\`\`bash
curl "wttr.in/Houston?format=3"
\`\`\`

### Forecast
\`\`\`bash
curl "wttr.in/Houston?format=v2"
\`\`\`
```

## Install

```ts
import skillLoaderPlugin from './plugin-skill-loader/src/index.ts';

export const projectAgent: ProjectAgent = {
  character: {
    ...character,
    settings: {
      skillLoader: {
        skillPaths: ['./skills', '/path/to/openclaw/skills'],
        autoLoad: true,
        enableCommands: true,
        allowShellExecution: false, // Security: off by default
      },
    },
  },
  plugins: [skillLoaderPlugin],
};
```

## What Gets Generated

For each SKILL.md, the plugin creates:

### 1. Main Action
- Named `SKILL_<NAME>` (e.g., `SKILL_WEATHER`)
- Validates against "When to Use" triggers
- Rejects based on "When NOT to Use" anti-triggers
- Provides skill instructions to the agent

### 2. Command Actions (if enabled)
- One per bash/shell code block
- Named `SKILL_<NAME>_CMD_<LABEL>`
- Shows the command (or executes if `allowShellExecution: true`)

### 3. Context Provider
- Named `skill-<name>-context`
- Injects skill instructions when the conversation is relevant
- Keyword-based relevance matching from description

## Dynamic Loading

### Via conversation
```
User: "Load skill from ./skills/weather/SKILL.md"
Agent: Loaded weather skill! 3 actions, 1 provider.

User: "What skills do you have?"
Agent: 1. 🌤️ weather — Get weather and forecasts (2 commands)

User: "Generate a plugin from the weather skill"
Agent: Generated at ./generated-plugins/plugin-weather/
```

### Programmatic
```ts
const loader = runtime.getService('skill-loader') as SkillLoaderService;

// Load from file
await loader.loadSkillFile('./skills/weather/SKILL.md');

// Load from string
await loader.loadSkillFromContent(markdownContent);

// Query
const skills = loader.getSkills();
const weather = loader.getSkill('weather');

// Unload
loader.unloadSkill('weather');
```

## Generating Standalone Plugins

The `GENERATE_PLUGIN` action exports a loaded skill as a full TypeScript plugin directory:

```
generated-plugins/plugin-weather/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts
    ├── actions/
    │   └── weatherAction.ts
    └── providers/
        └── weatherProvider.ts
```

Ready to `npm publish` or use directly.

## Security

- **Shell execution is OFF by default** (`allowShellExecution: false`)
- When off, command actions show the command but don't run it
- Commands have a configurable timeout (`commandTimeoutMs`, default 30s)
- Enable only in trusted environments

## Parser Details

The `SkillParser` extracts:
- **Frontmatter**: name, description, homepage, metadata (emoji, required bins)
- **Triggers**: Bullet items under "When to Use" headings
- **Anti-triggers**: Bullet items under "When NOT to Use" headings
- **Commands**: Fenced code blocks with language tags
- **Sections**: All markdown headings and their content
- **References**: All URLs found in the document
- **Examples**: Bullet items under "Examples" headings

## License

MIT