Skip to main content

External Skill Loader

The External Skill Loader provides runtime skill discovery and loading from external sources, including the Skills.sh API (27,000+ community skills), GitHub skill registries, and .well-known endpoints (RFC 8615).

Installation

import { createExternalSkillLoader } from 'auto-skill';

Usage

Basic Example

const loader = createExternalSkillLoader({
  githubToken: process.env.GITHUB_TOKEN, // Optional
  cacheTtl: 86400, // Cache duration in seconds (default: 24 hours)
});

// Start the loader (initializes cache cleanup)
await loader.start();

try {
  // Search for skills
  const response = await loader.search('react testing', {
    limit: 5,
    includeContent: false,
  });

  console.log(`Found ${response.count} skills`);
  for (const skill of response.skills) {
    console.log(`- ${skill.title} (${skill.installCount} installs)`);
  }
} finally {
  // Stop the loader when done
  await loader.stop();
}

API Reference

createExternalSkillLoader(options?)

Factory function to create an External Skill Loader instance.
options
object
Configuration options for the loader.
options.githubToken
string
GitHub personal access token for API requests. Increases rate limits and allows access to private repositories.
options.cacheTtl
number
default:"86400"
Cache time-to-live in seconds. Default is 86400 (24 hours).
loader
ExternalSkillLoader
An instance of the External Skill Loader.

search(query, options?)

Search for skills across all enabled sources.
query
string
required
Search query string (e.g., “react testing”, “nextjs deployment”).
options
object
Search configuration options.
options.limit
number
default:"10"
Maximum number of results to return.
options.includeContent
boolean
default:"false"
Whether to fetch full SKILL.md content. Set to true to load complete skill files.
response
SkillSearchResponse
Search results containing skills and metadata.
query
string
The original search query.
count
number
Number of skills returned.
skills
ExternalSkill[]
Array of matching skills.

start()

Start the loader and initialize cache cleanup intervals.
await loader.start();

stop()

Stop the loader and clear cache cleanup intervals.
await loader.stop();

getCacheStats()

Get cache statistics.
stats
object
size
number
Number of cached entries.
hits
number
Cache hit count.
misses
number
Cache miss count.

Types

ExternalSkill

Skill metadata from external sources.
ExternalSkill
object
id
string
Unique skill identifier.
title
string
Skill title/name.
description
string | null
Human-readable description of the skill.
source
string
Repository source in owner/repo format.
installCount
number
Number of times the skill has been installed.
relevanceScore
number
Relevance score based on search query.
content
string | null
Full SKILL.md content (only populated when includeContent: true).
rawUrl
string | null
Raw GitHub URL to the SKILL.md file.
skillsShUrl
string | null
Skills.sh page URL.
githubUrl
string | null
GitHub repository URL.
version
string
Skill version.
allowedTools
string[]
List of tools this skill can use.
tags
string[]
Skill tags/categories.
fetchError
string
Error message if content fetch failed.

SkillSearchResponse

Response from a skill search operation.
SkillSearchResponse
object
query
string
The search query that was executed.
count
number
Number of skills in the results.
skills
ExternalSkill[]
Array of matching skills, sorted by relevance.

Advanced Usage

Fetching Full Skill Content

const loader = createExternalSkillLoader();
await loader.start();

try {
  const response = await loader.search('nextjs', {
    limit: 1,
    includeContent: true, // Fetch full SKILL.md content
  });

  if (response.skills.length > 0) {
    const skill = response.skills[0];
    console.log('Full SKILL.md content:');
    console.log(skill.content);
    console.log(`Raw URL: ${skill.rawUrl}`);
  }
} finally {
  await loader.stop();
}

Caching Strategy

The loader automatically caches skill content to reduce API calls:
  • Default cache TTL: 24 hours
  • Cache cleanup runs every 5 minutes
  • Cached entries are stored in memory
const loader = createExternalSkillLoader({
  cacheTtl: 3600, // 1 hour cache
});

// Check cache statistics
const stats = await loader.getCacheStats();
console.log(`Cache has ${stats.size} entries`);

Sources

The loader searches the following sources:
  1. Skills.sh API: Community registry with 27,000+ skills
  2. GitHub Registries: Direct repository searches
  3. .well-known Endpoints: RFC 8615 skill discovery

Error Handling

try {
  const response = await loader.search('react');
  
  for (const skill of response.skills) {
    if (skill.fetchError) {
      console.error(`Failed to load ${skill.title}: ${skill.fetchError}`);
    }
  }
} catch (error) {
  console.error('Search failed:', error);
}

Build docs developers (and LLMs) love