@asterlabs/loader

Universal skills loader for AI agent frameworks with progressive disclosure

The official TypeScript/JavaScript SDK for the Asterism skills registry. Load AI agent skills into any framework with progressive disclosure support.

Features

• Progressive Disclosure: Load skills at different levels (metadata, contract, summary, full)
• Framework Support: Convert to LangChain, OpenAI, Anthropic tool formats
• Type-Safe: Full TypeScript definitions
• Smart Caching: Automatic caching with configurable TTL
• Token Budget: Load skills within context budget constraints

Installation

npm install @asterlabs/loader
# or
pnpm add @asterlabs/loader
# or
yarn add @asterlabs/loader

Quick Start

import { SkillsLoader, LoadLevel } from "@asterlabs/loader";

// Create a loader
const loader = new SkillsLoader();

// Load a skill with full content
const skill = await loader.load("pdf-tools");
console.log(skill.metadata.name); // 'pdf-tools'
console.log(skill.metadata.version); // '2.1.0'

// Progressive disclosure - load only what you need
const metadata = await loader.load("pdf-tools", { level: "metadata" }); // ~50 tokens
const contract = await loader.load("pdf-tools", { level: "contract" }); // ~300 tokens
const summary = await loader.load("pdf-tools", { level: "summary" }); // ~500 tokens
const full = await loader.load("pdf-tools", { level: "full" }); // Full content

// Load within a token budget
const budgeted = await loader.loadWithBudget("pdf-tools", 500);

Configuration

const loader = new SkillsLoader({
  apiKey: "aster_live_xxx", // For private skills
  baseUrl: "https://www.joinasterism.com/api/v1", // Custom registry
  cacheTtl: 3600, // Cache duration in seconds
  debug: true, // Enable debug logging
});

Framework Tool Conversion

Convert loaded skills to framework-specific tool formats:

import { toFrameworkTool, createTools } from "@asterlabs/loader";

const skill = await loader.load("pdf-tools", { level: "contract" });

// LangChain format
const langchainTool = toFrameworkTool(skill, "langchain");

// OpenAI function calling format
const openaiTool = toFrameworkTool(skill, "openai");
// { type: 'function', function: { name, description, parameters } }

// Anthropic tool use format
const anthropicTool = toFrameworkTool(skill, "anthropic");
// { name, description, input_schema }

// Create multiple tools at once
const tools = await createTools(["pdf-tools", "git-commit", "code-review"], "openai");

Skill Execution

Execute skills in the hosted runtime:

// Synchronous execution
const result = await loader.execute("pdf-tools", {
  file_path: "document.pdf",
  extract: "text",
});
console.log(result.outputs); // { text: '...', pages: 5 }

// Async execution
const asyncResult = await loader.execute("pdf-tools", { file_path: "large.pdf" }, { async: true });
console.log(asyncResult.executionId); // 'exec-abc123'

// Check status
const status = await loader.getExecutionStatus(asyncResult.executionId);
console.log(status.status); // 'completed'

Search and Discovery

// Search for skills
const results = await loader.search("code generation", 10);
for (const skill of results) {
  console.log(`${skill.fullName}: ${skill.description}`);
}

// List by category
const skills = await loader.list({
  category: "testing",
  sort: "downloads",
  limit: 20,
});

Type Definitions

Full TypeScript types are provided:

import {
  LoadLevel,
  LoaderConfig,
  SkillMetadata,
  SkillContract,
  SkillParameter,
  CapabilityDeclaration,
  LoadedSkill,
  ToolDefinition,
  ExecuteResult,
  LoadOptions,
  ExecuteOptions,
} from "@asterlabs/loader";

API Reference

SkillsLoader

| Method | Description | | ------------------------------------------- | ---------------------------------------- | | load(name, options) | Load a skill with progressive disclosure | | loadWithBudget(name, maxTokens, priority) | Load within token budget | | search(query, limit) | Search for skills | | list(options) | List popular skills | | execute(name, inputs, options) | Execute in hosted runtime | | getExecutionStatus(id) | Check execution status | | clearCache() | Clear skill cache |

LoadLevel

| Level | Description | ~Tokens | | ---------- | ------------------------------- | -------- | | metadata | Name, version, description | ~50 | | contract | + inputs, outputs, capabilities | ~300 | | summary | + first section | ~500 | | full | Complete skill content | Variable |

LoadOptions

interface LoadOptions {
  level?: LoadLevel; // Loading level
  version?: string; // Specific version
  maxTokens?: number; // Token budget
  priority?: string[]; // Priority sections
}

Convenience Functions

For simple use cases:

import { loadSkill, searchSkills, executeSkill, getLoader } from "@asterlabs/loader";

// Use default loader
const skill = await loadSkill("pdf-tools");
const results = await searchSkills("testing");
const result = await executeSkill("pdf-tools", { file: "doc.pdf" });

// Get/configure default loader
const loader = getLoader({ apiKey: "xxx" });

License

MIT