Skill Providers

Auto-Skill’s provider system enables pluggable skill discovery from multiple sources: local filesystem, Skills.sh community registry, and RFC 8615 well-known endpoints.

Provider Architecture

All skill providers implement the SkillProvider interface:

SkillProvider Interface

export interface SkillProvider {
  /** Human-readable name (e.g., 'Skills.sh') */
  readonly name: string;
  
  /** Short identifier (e.g., 'skillssh', 'local', 'wellknown') */
  readonly sourceId: string;
  
  /** Search for skills matching a query */
  search(query: string, limit?: number): Promise<SkillSearchResult[]>;
  
  /** Get detailed information about a specific skill */
  getSkillDetails(skillId: string): Promise<SkillSearchResult | null>;
  
  /** Check if this provider is currently available */
  isAvailable(): boolean;
}

Built-in Providers

Local Provider
Skills.sh Provider
Well-Known Provider

Searches your local filesystem for existing SKILL.md files.

Local Provider

import { createLocalProvider } from '@matrixy/auto-skill';

const local = createLocalProvider([
  '~/.claude/skills',
  '~/.cursor/skills',
  '~/.aider/skills'
]);

const results = await local.search('testing', 10);
console.log(results);
// [
//   {
//     id: 'jest-tdd',
//     name: 'Jest TDD Workflow',
//     description: 'Test-driven development with Jest',
//     source: 'local',
//     confidence: 0.85,
//     metadata: {
//       path: '~/.claude/skills/jest-tdd/SKILL.md',
//       autoGenerated: true
//     }
//   }
// ]

Features:

Parses YAML frontmatter from SKILL.md files
Searches by name, description, and tags
Supports multiple skill directories
Always available (no network required)

Connects to the Skills.sh community registry with 27,000+ skills.

Skills.sh Provider

import { createSkillsshProvider } from '@matrixy/auto-skill';

const skillssh = createSkillsshProvider({
  apiUrl: 'https://api.skills.sh',
  timeout: 10
});

const results = await skillssh.search('react testing', 5);
console.log(results);
// [
//   {
//     id: 'user/react-test-patterns',
//     name: 'React Test Patterns',
//     description: 'Comprehensive React testing strategies',
//     source: 'skillssh',
//     confidence: 0.75,
//     author: 'user',
//     tags: ['react', 'testing', 'jest'],
//     installCount: 1523,
//     sourceUrl: 'https://github.com/user/react-test-patterns',
//     compatibleAgents: ['claude', 'cursor', 'aider']
//   }
// ]

Features:

Full-text search across 27,000+ community skills
Install counts and ratings
Multi-agent compatibility metadata
Automatic caching and rate limiting

Discovers skills from websites using RFC 8615 /.well-known/agent-skills.json.

Well-Known Provider

import { createWellKnownProvider } from '@matrixy/auto-skill';

const wellknown = createWellKnownProvider(
  ['example.com', 'company.internal'],
  { timeout: 10, cacheTtl: 900 }
);

const results = await wellknown.search('deployment', 10);

Example manifest:

https://example.com/.well-known/agent-skills.json

{
  "skills": [
    {
      "id": "k8s-deploy",
      "name": "Kubernetes Deployment",
      "description": "Deploy services to Kubernetes clusters",
      "author": "Platform Team",
      "tags": ["k8s", "deployment", "devops"],
      "url": "https://example.com/skills/k8s-deploy",
      "compatible_agents": ["claude", "cursor"],
      "version": "1.0.0"
    }
  ]
}

Features:

Standards-based discovery (RFC 8615)
Caching with configurable TTL (default 15 min)
Graceful fallback when endpoints are unavailable
Ideal for internal/enterprise skill distribution

Provider Manager

The Provider Manager orchestrates multiple providers with priority ordering:

Using Provider Manager

import { createProviderManager, createLocalProvider } from '@matrixy/auto-skill';

const manager = createProviderManager();

// Register providers (first = highest priority)
manager.register(createLocalProvider());
manager.register(createSkillsshProvider());
manager.register(createWellKnownProvider(['example.com']));

// Search all providers
const results = await manager.searchAll('testing', 10);

// Results are:
// 1. Merged from all available providers
// 2. Deduplicated by (source, id) key
// 3. Ordered by provider priority
// 4. Truncated to limit

How It Works

Check Availability

The manager checks each provider’s isAvailable() method before querying.

Parallel Search

Available providers are queried in parallel for performance.

Merge Results

Results are collected and merged, preserving provider priority.

Deduplication

Skills with the same (source, id) key are deduplicated.

Limit and Return

The final list is truncated to the requested limit.

Creating Custom Providers

You can implement custom providers for internal registries, Git repositories, or other sources:

Custom Provider Example

import type { SkillProvider, SkillSearchResult } from '@matrixy/auto-skill';

class GitHubProvider implements SkillProvider {
  readonly name = 'GitHub Skills';
  readonly sourceId = 'github';
  
  constructor(private token?: string) {}
  
  async search(query: string, limit: number = 10): Promise<SkillSearchResult[]> {
    const response = await fetch(
      `https://api.github.com/search/repositories?q=${query}+topic:agent-skill`,
      {
        headers: {
          'Authorization': this.token ? `token ${this.token}` : '',
          'Accept': 'application/vnd.github.v3+json'
        }
      }
    );
    
    const data = await response.json();
    
    return data.items.slice(0, limit).map((repo: any) => ({
      id: repo.full_name,
      name: repo.name,
      description: repo.description || '',
      source: 'github',
      confidence: 0.6,
      author: repo.owner.login,
      tags: repo.topics || [],
      installCount: repo.stargazers_count,
      sourceUrl: repo.html_url,
      compatibleAgents: [],
      metadata: {
        stars: repo.stargazers_count,
        forks: repo.forks_count,
        updatedAt: repo.updated_at
      }
    }));
  }
  
  async getSkillDetails(skillId: string): Promise<SkillSearchResult | null> {
    const response = await fetch(
      `https://api.github.com/repos/${skillId}`,
      {
        headers: {
          'Authorization': this.token ? `token ${this.token}` : '',
          'Accept': 'application/vnd.github.v3+json'
        }
      }
    );
    
    if (!response.ok) return null;
    
    const repo = await response.json();
    
    return {
      id: repo.full_name,
      name: repo.name,
      description: repo.description || '',
      source: 'github',
      confidence: 0.6,
      author: repo.owner.login,
      tags: repo.topics || [],
      installCount: repo.stargazers_count,
      sourceUrl: repo.html_url,
      compatibleAgents: [],
      metadata: {
        stars: repo.stargazers_count,
        forks: repo.forks_count,
        language: repo.language,
        license: repo.license?.spdx_id,
        readme: repo.readme_url
      }
    };
  }
  
  isAvailable(): boolean {
    // Check if GitHub API is reachable
    return true;
  }
}

// Usage
const github = new GitHubProvider(process.env.GITHUB_TOKEN);
manager.register(github);

Provider Configuration

Configure enabled providers and well-known domains:

.claude/auto-skill.local.md

---
providers:
  enabled_providers:
    - local
    - skillssh
    - wellknown
  wellknown_domains:
    - company.internal
    - skills.example.com
---

Loading Provider Config

import { loadConfig } from '@matrixy/auto-skill';

const config = loadConfig('/path/to/project');

console.log(config.providers);
// {
//   enabledProviders: ['local', 'skillssh', 'wellknown'],
//   wellknownDomains: ['company.internal', 'skills.example.com']
// }

Proactive Discovery Integration

Providers power Auto-Skill’s Proactive Discovery feature:

Proactive Discovery with Providers

import {
  createExternalSkillLoader,
  createProactiveDiscovery,
  createSkillRecommendationEngine
} from '@matrixy/auto-skill';

const loader = createExternalSkillLoader({
  githubToken: process.env.GITHUB_TOKEN
});

const discovery = createProactiveDiscovery(loader);
const engine = createSkillRecommendationEngine(loader, discovery);

await loader.start();

// Search across all providers
const response = await loader.search('react testing', { limit: 5 });
console.log(response.skills);

// Get recommendations for a detected pattern
const recommendations = await engine.recommendForPattern(detectedPattern);
console.log(recommendations);
// [
//   {
//     type: 'hybrid',
//     externalSkill: { title: 'React Test Patterns', ... },
//     localPattern: { ... },
//     reason: 'Your workflow matches "React Test Patterns". Use it instead?',
//     confidence: 0.9,
//     action: 'graduate'
//   }
// ]

await loader.stop();

Best Practices

Provider Priority

Local — Skills you’ve already adopted
Well-Known (Internal) — Company/team-approved skills
Skills.sh — Community skills with high install counts
Well-Known (External) — Third-party public endpoints

Caching Strategy

Local provider: No caching needed (filesystem is fast)
Skills.sh: Cached by the API server
Well-Known: Cache for 15 minutes (configurable)

Adjust cache TTL based on update frequency:

createWellKnownProvider(['example.com'], {
  cacheTtl: 3600  // 1 hour for stable internal registries
});

Error Handling

The provider manager gracefully handles failures:

// If Skills.sh is down, local and well-known still work
const results = await manager.searchAll('testing', 10);

// Errors are logged but don't throw
// [ProviderManager] Provider 'Skills.sh' search failed: ECONNREFUSED

Rate Limiting

Respect API rate limits:

Skills.sh: 100 requests/hour (unauthenticated), 5000/hour (authenticated)
Well-Known: No standard rate limit, but be respectful
GitHub API: 60 requests/hour (unauthenticated), 5000/hour (authenticated)

Provider Comparison

Feature	Local	Skills.sh	Well-Known
Network Required	No	Yes	Yes
Setup	None	Optional token	Domain list
Skill Count	Varies	27,000+	Varies
Search Speed	Fast	Medium	Medium
Caching	N/A	Server-side	Client-side
Authentication	N/A	Optional	N/A
Best For	Personal skills	Community discovery	Enterprise/internal

Get Started

Core Modules

Features

CLI Reference

Guides

Provider Architecture

Built-in Providers

Provider Manager

How It Works

Creating Custom Providers

Provider Configuration

Proactive Discovery Integration

Best Practices

Provider Comparison

Next Steps

Configuration

Proactive Discovery

Build docs developers (and LLMs) love

Get Started

Core Modules

Features

CLI Reference

Guides

​Provider Architecture

​Built-in Providers

​Provider Manager

​How It Works

​Creating Custom Providers

​Provider Configuration

​Proactive Discovery Integration

​Best Practices

​Provider Comparison

​Next Steps

Configuration

Proactive Discovery

Build docs developers (and LLMs) love

Provider Architecture

Built-in Providers

Provider Manager

How It Works

Creating Custom Providers

Provider Configuration

Proactive Discovery Integration

Best Practices

Provider Comparison

Next Steps