@asterlabs/loader

@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