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

npm install
npm run example

Basic Usage

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:

---
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

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

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:

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