Skill Providers

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

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

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

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

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']
// }

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();