npm package: @icarusmx/skillful
Description: Lightweight agent orchestration framework with progressive disclosure for token-efficient AI interactions
Author: Icarus MX
Latest version: 0.1.1

# Skillful

Lightweight agent orchestration framework with progressive disclosure for token-efficient AI interactions.

## Why Skillful?

Inspired by Claude Code's skills architecture, Skillful solves the context window problem in agent orchestration by implementing **progressive disclosure** - only loading skill content when actually needed.

**The Problem:**
- Traditional agent frameworks load all capabilities upfront
- Wastes tokens on unused functionality
- Hits context limits quickly

**The Solution:**
- Cheap discovery phase using only skill metadata
- On-demand loading of full skill content
- Tool restrictions for isolated execution
- Multi-tier skill storage (user/project/plugin)

## Quick Start

```bash
npm install
npm run example
```

## Basic Usage

```javascript
import { Skillful } from 'skillful'

// Initialize with skill paths
const skillful = new Skillful({
  paths: [
    '~/.skillful/skills',    // User-level skills
    './.skillful/skills'      // Project-level skills
  ]
})

await skillful.init()

// Token-efficient discovery (metadata only)
const skills = skillful.discover('review code')
// Returns: [{ name: 'code-review', description: '...', hasToolRestrictions: true }]

// Progressive disclosure - load only when needed
const skill = await skillful.load('code-review')

// Execute with custom logic
const result = await skillful.execute('code-review', {
  data: { files: ['src/app.js'] },
  executor: async (ctx) => {
    // Your execution logic here
    // Call LLM API, run scripts, etc.
    return { findings: [...] }
  }
})
```

## Architecture

### Core Components

1. **Skill** - Parses SKILL.md files with YAML frontmatter
2. **SkillRegistry** - Indexes and discovers skills across multiple paths
3. **SkillExecutor** - Manages execution with tool restrictions
4. **Skillful** - Main orchestrator tying everything together

### Progressive Disclosure

```
Discovery (cheap) → Selective Loading (on-demand) → Execution (isolated)
     ~50 bytes           ~2-5 KB                      Full context
```

## Skill Structure

Create a directory with a `SKILL.md` file:

```
my-skill/
  SKILL.md
  helper-docs.md
  examples/
```

**SKILL.md format:**

```markdown
---
name: my-skill
description: Brief description that helps with discovery (max 1024 chars)
allowed-tools:
  - read-file
  - grep
---

# Full skill instructions

Detailed content loaded only when skill is executed...
```

## Multi-tier Storage

1. **User-level** (`~/.skillful/skills/`)
   - Personal workflows across all projects

2. **Project-level** (`./.skillful/skills/`)
   - Team-shared capabilities in git

3. **Plugin-level**
   - Skills bundled with npm packages

## API Reference

### Skillful

```javascript
const skillful = new Skillful(options)
await skillful.init()                    // Scan all paths
skillful.discover(query)                 // Find relevant skills
await skillful.load(skillName)           // Load full content
await skillful.execute(skillName, ctx)   // Execute skill
skillful.list()                          // All skill names
skillful.stats()                         // Registry statistics
await skillful.addPath(path)             // Add skill directory
```

### Execution Context

```javascript
await skillful.execute('skill-name', {
  data: {},                              // Custom data
  executor: async (ctx) => {},           // Execution logic
  beforeExecute: async (ctx) => {},      // Hook
  afterExecute: async (ctx, result) => {},
  onError: async (ctx, error) => {}
})
```

### Tool Restrictions

Skills can specify allowed tools in frontmatter:

```yaml
allowed-tools:
  - read-file
  - grep
  - analyze
```

The executor enforces these restrictions during execution.

## Token Efficiency

**Without Skillful:**
```
Agent loads 50 skills × 3KB = 150KB upfront
```

**With Skillful:**
```
Discovery: 50 skills × 50 bytes = 2.5KB
Load 2 relevant skills × 3KB = 6KB
Total: 8.5KB (94% reduction)
```

## Philosophy

- **Simple, not enterprise** - Lightweight core, extensible by design
- **Progressive disclosure** - Load only what's needed, when it's needed
- **Token conscious** - Every byte counts in the context window era
- **Framework, not solution** - Provides structure, you provide logic

## Examples

See `examples/` directory for:
- Basic usage
- Custom executors
- Tool restrictions
- Multi-tier skill storage

## License

MIT