@elizaos/plugin-agent-skills 1.0.0

package/README.md

@@ -0,0 +1,372 @@
+# Agent Skills Plugin for elizaOS
+
+Implements the [Agent Skills specification](https://agentskills.io) with support for:
+- Spec-compliant SKILL.md parsing and validation
+- Progressive disclosure (metadata → instructions → resources)
+- ClawHub registry integration for skill discovery
+- Otto metadata compatibility for dependency management
+- **Dual storage modes**: Memory (browser/virtual FS) and Filesystem (Node.js/native)
+
+## Installation
+
+```bash
+npm install @elizaos/plugin-agent-skills
+```
+
+## Quick Start
+
+```typescript
+import { agentSkillsPlugin } from '@elizaos/plugin-agent-skills';
+
+// Add to your agent's plugins
+const agent = createAgent({
+  plugins: [agentSkillsPlugin],
+  // ...
+});
+```
+
+## Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `SKILLS_DIR` | Directory to load/install skills | `./skills` |
+| `SKILLS_AUTO_LOAD` | Load installed skills on startup | `true` |
+| `SKILLS_REGISTRY` | Skill registry URL | `https://clawhub.ai` |
+| `SKILLS_STORAGE_TYPE` | Storage mode: `memory`, `filesystem`, or `auto` | `auto` |
+
+## Storage Modes
+
+The plugin supports two storage backends for maximum flexibility:
+
+### Memory Storage (Browser/Virtual FS)
+
+Skills are stored entirely in memory. Use this for:
+- Browser environments without filesystem access
+- Virtual FS scenarios (sandboxed environments)
+- Ephemeral skill loading
+- Testing
+
+```typescript
+import { AgentSkillsService, MemorySkillStore } from '@elizaos/plugin-agent-skills';
+
+// Create with explicit memory storage
+const service = await AgentSkillsService.start(runtime, {
+  storageType: 'memory',
+});
+
+// Or use the store directly
+const store = new MemorySkillStore('/virtual/skills');
+await store.initialize();
+
+// Load skills from content (no filesystem required)
+await store.loadFromContent('my-skill', skillMdContent, additionalFiles);
+
+// Load skills from downloaded zip
+await store.loadFromZip('github', zipBuffer);
+```
+
+### Filesystem Storage (Node.js/Native)
+
+Skills are stored on disk. Use this for:
+- Node.js server environments
+- CLI tools
+- Persistent skill installations
+
+```typescript
+import { AgentSkillsService, FileSystemSkillStore } from '@elizaos/plugin-agent-skills';
+
+// Create with explicit filesystem storage
+const service = await AgentSkillsService.start(runtime, {
+  storageType: 'filesystem',
+  skillsDir: './my-skills',
+});
+
+// Or use the store directly
+const store = new FileSystemSkillStore('./skills');
+await store.initialize();
+```
+
+### Auto Detection
+
+By default (`storageType: 'auto'`), the plugin detects the environment:
+- Browser environments → Memory storage
+- Node.js environments → Filesystem storage
+
+```typescript
+import { createStorage } from '@elizaos/plugin-agent-skills';
+
+// Auto-detect based on environment
+const storage = createStorage({ type: 'auto', basePath: './skills' });
+```
+
+### Transferring Skills Between Stores
+
+Skills can be transferred between storage backends:
+
+```typescript
+import { MemorySkillStore, FileSystemSkillStore, loadSkillFromStorage } from '@elizaos/plugin-agent-skills';
+
+// Load from filesystem
+const fsStore = new FileSystemSkillStore('./skills');
+await fsStore.initialize();
+const content = await fsStore.loadSkillContent('my-skill');
+
+// Transfer to memory
+const memStore = new MemorySkillStore();
+await memStore.initialize();
+await memStore.loadFromContent('my-skill', content);
+
+// Use skill
+const skill = await loadSkillFromStorage(memStore, 'my-skill');
+```
+
+## Progressive Disclosure
+
+The plugin implements progressive disclosure for efficient context management:
+
+### Level 1: Metadata (~100 tokens per skill)
+Skill name and description are always available in the system prompt.
+
+```xml
+<available_skills>
+  <skill>
+    <name>pdf-processing</name>
+    <description>Extract text and tables from PDF files.</description>
+    <location>/path/to/skills/pdf-processing/SKILL.md</location>
+  </skill>
+</available_skills>
+```
+
+### Level 2: Instructions (<5k tokens)
+Full SKILL.md body loaded when a skill is triggered.
+
+### Level 3: Resources (unlimited)
+Scripts, references, and assets loaded on-demand without entering context.
+
+## Skill Structure
+
+```
+my-skill/
+├── SKILL.md          # Required: instructions + metadata
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+└── assets/           # Optional: templates, resources
+```
+
+### SKILL.md Format
+
+```yaml
+---
+name: my-skill
+description: What this skill does and when to use it.
+license: MIT
+compatibility: Requires Python 3.10+
+metadata:
+  author: my-org
+  version: "1.0"
+  otto:
+    emoji: "🔧"
+    requires:
+      bins: ["my-cli"]
+    install:
+      - id: brew
+        kind: brew
+        formula: my-tool
+        bins: ["my-cli"]
+        label: "Install my-tool (brew)"
+---
+
+# My Skill
+
+Instructions here...
+```
+
+## Actions
+
+### GET_SKILL_GUIDANCE
+Main action for skill-powered assistance. Automatically finds, installs, and returns skill instructions.
+
+### SEARCH_SKILLS
+Search the registry for available skills.
+
+### GET_SKILL_DETAILS
+Get detailed information about a specific skill.
+
+### RUN_SKILL_SCRIPT
+Execute scripts bundled with installed skills.
+
+### SYNC_SKILL_CATALOG
+Refresh the skill catalog from the registry.
+
+## Providers
+
+### agent_skills (Medium Resolution)
+Lists installed skills with descriptions. Default provider.
+
+### agent_skill_instructions (High Resolution)
+Provides full instructions for contextually matched skills.
+
+### agent_skills_catalog (Dynamic)
+Shows available skill categories when user asks about capabilities.
+
+## Otto Compatibility
+
+The plugin supports Otto's extended metadata format for dependency management:
+
+```yaml
+metadata:
+  otto:
+    emoji: "🐙"
+    requires:
+      bins: ["gh"]
+    install:
+      - id: brew
+        kind: brew
+        formula: gh
+        bins: ["gh"]
+        label: "Install GitHub CLI (brew)"
+      - id: apt
+        kind: apt
+        package: gh
+        bins: ["gh"]
+        label: "Install GitHub CLI (apt)"
+```
+
+## API Reference
+
+### Service
+
+```typescript
+import { AgentSkillsService } from '@elizaos/plugin-agent-skills';
+
+// Get loaded skills
+const skills = service.getLoadedSkills();
+
+// Get skill instructions
+const instructions = service.getSkillInstructions('my-skill');
+
+// Read a reference file
+const content = await service.readReference('my-skill', 'api-docs.md');
+
+// Install a skill from registry
+await service.install('pdf-processing');
+
+// Check storage mode
+if (service.isMemoryMode()) {
+  // Load skill from content (memory mode only)
+  await service.loadSkillFromContent('custom-skill', skillMdContent);
+}
+```
+
+### Storage
+
+```typescript
+import {
+  MemorySkillStore,
+  FileSystemSkillStore,
+  createStorage,
+  loadSkillFromStorage,
+  type ISkillStorage,
+} from '@elizaos/plugin-agent-skills';
+
+// Create storage (auto-detects environment)
+const storage = createStorage({ type: 'auto', basePath: './skills' });
+await storage.initialize();
+
+// List installed skills
+const slugs = await storage.listSkills();
+
+// Load skill content
+const content = await storage.loadSkillContent('my-skill');
+
+// Load skill into a Skill object
+const skill = await loadSkillFromStorage(storage, 'my-skill');
+
+// Memory-specific: load from content
+if (storage.type === 'memory') {
+  await (storage as MemorySkillStore).loadFromContent('new-skill', content);
+}
+
+// Memory-specific: load from zip
+if (storage.type === 'memory') {
+  await (storage as MemorySkillStore).loadFromZip('downloaded-skill', zipBuffer);
+}
+```
+
+### Parser Utilities
+
+```typescript
+import {
+  parseFrontmatter,
+  validateFrontmatter,
+  generateSkillsXml,
+} from '@elizaos/plugin-agent-skills';
+
+// Parse SKILL.md content
+const { frontmatter, body } = parseFrontmatter(content);
+
+// Validate frontmatter
+const result = validateFrontmatter(frontmatter, 'skill-name');
+
+// Generate XML for prompts
+const xml = generateSkillsXml(skills, { includeLocation: true });
+```
+
+## Testing
+
+The plugin includes comprehensive tests across TypeScript, Python, and Rust implementations.
+
+### Run Tests (Without API Key)
+
+```bash
+# TypeScript - from monorepo root
+bun run --filter @elizaos/plugin-agent-skills test
+
+# Python
+cd plugins/plugin-agent-skills/python
+pip install -e ".[dev]"
+pytest tests/ -v
+
+# Rust
+cd plugins/plugin-agent-skills/rust
+cargo test
+```
+
+### Run Integration Tests with Anthropic API
+
+Integration tests verify that skills work end-to-end with a real Anthropic API. They load real Otto skills, format them for prompt injection, and verify the agent can understand and use the skill instructions.
+
+```bash
+# TypeScript
+ANTHROPIC_API_KEY=your-key bun run --filter @elizaos/plugin-agent-skills test
+
+# Python
+ANTHROPIC_API_KEY=your-key pytest tests/test_integration.py -v
+
+# Rust
+ANTHROPIC_API_KEY=your-key cargo test --test integration_tests
+```
+
+### Test Coverage
+
+| Language | Tests | Description |
+|----------|-------|-------------|
+| TypeScript | parser.test.ts | SKILL.md parsing, validation, XML generation |
+| TypeScript | storage.test.ts | Memory and filesystem storage backends |
+| TypeScript | integration.test.ts | Anthropic API integration, real skill loading |
+| Python | test_parser.py | Parser functions, frontmatter extraction |
+| Python | test_storage.py | Storage backends, skill loading |
+| Python | test_integration.py | Anthropic API integration |
+| Rust | parser_tests.rs | Parser, validation, XML generation |
+| Rust | integration_tests.rs | Storage, Anthropic API integration |
+
+## Related
+
+- [Agent Skills Specification](https://agentskills.io)
+- [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
+- [ClawHub Registry](https://clawhub.ai)
+- [Otto](https://github.com/otto)
+
+## License
+
+MIT